MFC r334100:
Document the return value of sbuf_bcat(9).

MFC r316549,r316550,r316551,r316554:

r316549:

Add sys/types.h #include to EXAMPLE to provide a complete functional
standalone example program

r316550:

sbuf(9): convert SYNOPSIS section from .Fn entries to .Fo/.Fa/.Fc entries

This shortens the column count on many lines considerably.

While here, add "(void)" to sbuf_new_auto(3) for consistency with style(9)
recommendations.

r316551:

sbuf(9): clarify kernel-only APIs

- move sbuf_bcopyin(9) and sbuf_copyin(9) near sbuf_new_for_sysctl(9), as
all three functions are kernel-only APIs.
- add #ifdef _KERNEL around sbuf_*copyin and sbuf_new_for_sysctl(9) to
make it visually clear that they are kernel-only APIs.

r316554:

sbuf(9): add MLINKS for sbuf_{clear,get,set}_flags(9)

These functions were added in r279992.

MFC r307873,r314397,r314399,r314419,r314420,r314533,r316553:

r307873 (by marcel):

Include <stdarg.h> instead of <machine/stdarg.h> when compiled as
part of libsbuf. The former is the standard header, and allows us
to compile libsbuf on macOS/linux.

r314397 (by scottl):

Implement sbuf_prf(), which takes an sbuf and outputs it
to stdout in the non-kernel case and to the console+log
in the kernel case. For the kernel case it hooks the
putbuf() machinery underneath printf(9) so that the buffer
is written completely atomically and without a copy into
another temporary buffer. This is useful for fixing
compound console/log messages that become broken and
interleaved when multiple threads are competing for the
console.

r314399 (by scottl):

Add prototype for sbuf_putbuf()

r314419 (by jkim):

Include stdio.h to fix libsbuf build.

r314420 (by scottl):

Provide a comment on why stdio.h needs to be included.

r314533 (by scottl):

Expose the sbuf_putbuf() symbol to libsbuf. There are a few other symbols
that are present but not exposed, like get/set/clear flags, not sure if they
need to be exposed at this point.

r316553:

sbuf(3): expose sbuf_{clear,get,set}_flags(3) via libsbuf

These functions were added to sbuf(9) in r279992, but never
exposed to userspace. Expose them now so they can be used/tested.

Copy head@r302406 to stable/11 as part of the 11.0-RELEASE cycle.
Prune svn:mergeinfo from the new branch, as nothing has been merged
here.

Additional commits post-branch will follow.

Approved by: re (implicit)
Sponsored by: The FreeBSD Foundation

Remove EOL whitespace.

Add support for reading MAM attributes to camcontrol(8) and libcam(3).

MAM is Medium Auxiliary Memory and is most commonly found as flash
chips on tapes.

This includes support for reading attributes and decoding most
known attributes, but does not yet include support for writing
attributes or reporting attributes in XML format.

libsbuf/Makefile:
Add subr_prf.c for the new sbuf_hexdump() function. This
function is essentially the same function.

libsbuf/Symbol.map:
Add a new shared library minor version, and include the
sbuf_hexdump() function.

libsbuf/Version.def:
Add version 1.4 of the libsbuf library.

libutil/hexdump.3:
Document sbuf_hexdump() alongside hexdump(3), since it is
essentially the same function.

camcontrol/Makefile:
Add attrib.c.

camcontrol/attrib.c:
Implementation of READ ATTRIBUTE support for camcontrol(8).

camcontrol/camcontrol.8:
Document the new 'camcontrol attrib' subcommand.

camcontrol/camcontrol.c:
Add the new 'camcontrol attrib' subcommand.

camcontrol/camcontrol.h:
Add a function prototype for scsiattrib().

share/man/man9/sbuf.9:
Document the existence of sbuf_hexdump() and point users to
the hexdump(3) man page for more details.

sys/cam/scsi/scsi_all.c:
Add a table of known attributes, text descriptions and
handler functions.

Add a new scsi_attrib_sbuf() function along with a number
of other related functions that help decode attributes.

scsi_attrib_ascii_sbuf() decodes ASCII format attributes.

scsi_attrib_int_sbuf() decodes binary format attributes, and
will pass them off to scsi_attrib_hexdump_sbuf() if they're
bigger than 8 bytes.

scsi_attrib_vendser_sbuf() decodes the vendor and drive
serial number attribute.

scsi_attrib_volcoh_sbuf() decodes the Volume Coherency
Information attribute that LTFS writes out.

sys/cam/scsi/scsi_all.h:
Add a number of attribute-related structure definitions and
other defines.

Add function prototypes for all of the functions added in
scsi_all.c.

sys/kern/subr_prf.c:
Add a new function, sbuf_hexdump(). This is the same as
the existing hexdump(9) function, except that it puts the
result in an sbuf.

This also changes subr_prf.c so that it can be compiled in
userland for includsion in libsbuf.

We should work to change this so that the kernel hexdump
implementation is a wrapper around sbuf_hexdump() with a
statically allocated sbuf with a drain. That will require
a drain function that goes to the kernel printf() buffer
that can take a non-NUL terminated string as input.
That is because an sbuf isn't NUL-terminated until it is
finished, and we don't want to finish it while we're still
using it.

We should also work to consolidate the userland hexdump and
kernel hexdump implemenatations, which are currently
separate. This would also mean making applications that
currently link in libutil link in libsbuf.

sys/sys/sbuf.h:
Add the prototype for sbuf_hexdump(), and add another copy
of the hexdump flag values if they aren't already defined.

Ideally the flags should be defined in one place but the
implemenation makes it difficult to do properly. (See
above.)

Sponsored by: Spectra Logic Corporation
MFC after: 1 week

Add a new flag, SBUF_INCLUDENUL, and new get/set/clear functions for flags.

The SBUF_INCLUDENUL flag causes the nulterm byte at the end of the string
to be counted in the length of the data. If copying the data using the
sbuf_data() and sbuf_len() functions, or if writing it automatically with
a drain function, the net effect is that the nulterm byte is copied along
with the rest of the data.

use .Mt to mark up email addresses consistently (part6)

PR: 191174
Submitted by: Franco Fichtner <franco at lastsummer.de>

Document sbuf_start_section() and sbuf_end_section() functions.

MFC after: 1 month

Fix synopsis for sbuf_len.

MFC after: 3 days

Follow style(9) more closely in the example.

sbuf_data() hasn't returned NULL for overflowed buffers since r71721.

- Fix markup.
- Remove trailing whitespace.

Re-encode files from ISO-8859-1 to UTF-8

When adding examples to man-pages, try to make them at least
look like they might work.

Prodded by: Vadim Goncharov

Try to explain what sbufs do and add an example to show it.

Clarify return values.

Remove duplicate sentence.

Explicitly wire the user buffer rather than doing it implicitly in
sbuf_new_for_sysctl(9). This allows using an sbuf with a SYSCTL_OUT
drain for extremely large amounts of data where the caller knows that
appropriate references are held, and sleeping is not an issue.

Inspired by: rwatson

Document sbuf_new_for_sysctl(9).

Pointed out by: lstewart

Replace sbuf_overflowed() with sbuf_error(), which returns any error
code associated with overflow or with the drain function. While this
function is not expected to be used often, it produces more information
in the form of an errno that sbuf_overflowed() did.

Add drain functionality to sbufs. The drain is a function that is
called when the sbuf internal buffer is filled. For kernel sbufs with a
drain, the internal buffer will never be expanded. For userland sbufs
with a drain, the internal buffer may still be expanded by
sbuf_[v]printf(3).

Sbufs now have three basic uses:
1) static string manipulation. Overflow is marked.
2) dynamic string manipulation. Overflow triggers string growth.
3) drained string manipulation. Overflow triggers draining.

In all cases the manipulation is 'safe' in that overflow is detected and
managed.

Reviewed by: phk (the previous version)

Fix small errors in the sbuf(9) man page.

Document sbuf_new_auto().

While here, add a missing `-' in phk's name.

MFC after: 3 days

Markup fixes.

Make sbuf_copyin() return the number of bytes copied on success.

Submitted by: "Wojciech A. Koszek" <dunstan@freebsd.czest.pl>

Bump document date.

Reminded by: ru

The type and name of sbuf_b{cat,cpy}()'s second argument have changed.

I don't normally use my middle name, so remove it from attributions in
man pages (though not from copyright notices). While I'm here, add email
addresses where appropriate.

Move the description of sbuf_delete() closer to the description of
sbuf_new(), and try to make them both a little clearer.

mdoc(7): Use the new feature of the .In macro.

Add the new function "sbuf_done()" which returns non-zero if the sbuf is
finished.

This allows sbufs to be used for request/response scenarioes without
needing additional communication flags.

Sponsored by: DARPA & NAI Labs.

mdoc(7) police: tidy up the previous delta a bit.

Document sbuf_trim() and sbuf_vprintf(); add MLINKs.
Clarify that the contents of a caller-supplied buffer are undefined and
should not be examined directly.

Reviewed by: des

- Cross reference the section 9 printf man page since it contains
information with regards to in-kernel format directives that are
not in printf.3

Fixed (C) syntax error in synopsis.

mdoc(7) police: Use the new .In macro for #include statements.

4.4 will have sbufs.

mdoc(7) police: removed HISTORY info from the .Os call.

Constify the format string.

Submitted by: Mike Barcroft <mike@q9media.com>
Forgotten by: des

mdoc(7) police: mark type with .Vt, sort xrefs.

Add sbuf_copyin(). Also add 'b' variants of sbuf_{cat,copyin,cpy}() which
ignore NUL bytes in the source string.

sbuf_new(9) now returns a struct sbuf * instead of an int. If the caller
does not provide a struct sbuf, sbuf_new(9) will allocate one and return
a pointer to it.

mdoc(7) police: update HISTORY section.
This interface is not available in 4.3-RELEASE.

mdoc(7) police: uppercase document title.

Rewrite of the CAM error recovery code.

Some of the major changes include:

- The SCSI error handling portion of cam_periph_error() has
been broken out into a number of subfunctions to better
modularize the code that handles the hierarchy of SCSI errors.
As a result, the code is now much easier to read.

- String handling and error printing has been significantly
revamped. We now use sbufs to do string formatting instead
of using printfs (for the kernel) and snprintf/strncat (for
userland) as before.

There is a new catchall error printing routine,
cam_error_print() and its string-based counterpart,
cam_error_string() that allow the kernel and userland
applications to pass in a CCB and have errors printed out
properly, whether or not they're SCSI errors. Among other
things, this helped eliminate a fair amount of duplicate code
in camcontrol.

We now print out more information than before, including
the CAM status and SCSI status and the error recovery action
taken to remedy the problem.

- sbufs are now available in userland, via libsbuf. This
change was necessary since most of the error printing code
is shared between libcam and the kernel.

- A new transfer settings interface is included in this checkin.
This code is #ifdef'ed out, and is primarily intended to aid
discussion with HBA driver authors on the final form the
interface should take. There is example code in the ahc(4)
driver that implements the HBA driver side of the new
interface. The new transfer settings code won't be enabled
until we're ready to switch all HBA drivers over to the new
interface.

src/Makefile.inc1,
lib/Makefile: Add libsbuf. It must be built before libcam,
since libcam uses sbuf routines.

libcam/Makefile: libcam now depends on libsbuf.

libsbuf/Makefile: Add a makefile for libsbuf. This pulls in the
sbuf sources from sys/kern.

bsd.libnames.mk: Add LIBSBUF.

camcontrol/Makefile: Add -lsbuf. Since camcontrol is statically
linked, we can't depend on the dynamic linker
to pull in libsbuf.

camcontrol.c: Use cam_error_print() instead of checking for
CAM_SCSI_STATUS_ERROR on every failed CCB.

sbuf.9: Change the prototypes for sbuf_cat() and
sbuf_cpy() so that the source string is now a
const char *. This is more in line wth the
standard system string functions, and helps
eliminate warnings when dealing with a const
source buffer.

Fix a typo.

cam.c: Add description strings for the various CAM
error status values, as well as routines to
look up those strings.

Add new cam_error_string() and
cam_error_print() routines for userland and
the kernel.

cam.h: Add a new CAM flag, CAM_RETRY_SELTO.

Add enumerated types for the various options
available with cam_error_print() and
cam_error_string().

cam_ccb.h: Add new transfer negotiation structures/types.

Change inq_len in the ccb_getdev structure to
be "reserved". This field has never been
filled in, and will be removed when we next
bump the CAM version.

cam_debug.h: Fix typo.

cam_periph.c: Modularize cam_periph_error(). The SCSI error
handling part of cam_periph_error() is now
in camperiphscsistatuserror() and
camperiphscsisenseerror().

In cam_periph_lock(), increase the reference
count on the periph while we wait for our lock
attempt to succeed so that the periph won't go
away while we're sleeping.

cam_xpt.c: Add new transfer negotiation code. (ifdefed
out)

Add a new function, xpt_path_string(). This
is a string/sbuf analog to xpt_print_path().

scsi_all.c: Revamp string handing and error printing code.
We now use sbufs for much of the string
formatting code. More of that code is shared
between userland the kernel.

scsi_all.h: Get rid of SS_TURSTART, it wasn't terribly
useful in the first place.

Add a new error action, SS_REQSENSE. (Send a
request sense and then retry the command.)
This is useful when the controller hasn't
performed autosense for some reason.

Change the default actions around a bit.

scsi_cd.c,
scsi_da.c,
scsi_pt.c,
scsi_ses.c: SF_RETRY_SELTO -> CAM_RETRY_SELTO. Selection
timeouts shouldn't be covered by a sense flag.

scsi_pass.[ch]: SF_RETRY_SELTO -> CAM_RETRY_SELTO.

Get rid of the last vestiges of a read/write
interface.

libkern/bsearch.c,
sys/libkern.h,
conf/files: Add bsearch.c, which is needed for some of the
new table lookup routines.

aic7xxx_freebsd.c: Define AHC_NEW_TRAN_SETTINGS if
CAM_NEW_TRAN_CODE is defined.

sbuf.h,
subr_sbuf.c: Add the appropriate #ifdefs so sbufs can
compile and run in userland.

Change sbuf_printf() to use vsnprintf()
instead of kvprintf(), which is only available
in the kernel.

Change the source string for sbuf_cpy() and
sbuf_cat() to be a const char *.

Add __BEGIN_DECLS and __END_DECLS around
function prototypes since they're now exported
to userland.

kdump/mkioctls: Include stdio.h before cam.h since cam.h now
includes a function with a FILE * argument.

Submitted by: gibbs (mostly)
Reviewed by: jdp, marcel (libsbuf makefile changes)
Reviewed by: des (sbuf changes)
Reviewed by: ken

Fixed missing and/or wrong and/or extra includes in synopsis.

Document the changes in subr_sbuf.c rev. 1.2.

Grammar fix.

Add sbuf(9) man page with links to API function names.

Reviewed by: ru