sg_lib: document internal json interface in include/sg_pr2serr.h; codespell fixes

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@952 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 120 insertions, 0 deletions

diff --git a/doc/sg3_utils_json.8 b/doc/sg3_utils_json.8
new file mode 100644
index 00000000..161c3583
--- /dev/null
+++ b/doc/sg3_utils_json.8
@@ -0,0 +1,120 @@
+.TH SG3_UTILS "8" "May 2022" "sg3_utils\-1.48" SG3_UTILS
+.SH NAME
+sg3_utils \- JSON output for some utilities
+.SH SYNOPSIS
+.B sg_*
+\fI\-\-json[=JO]\fR [\fIOTHER_OPTIONS\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+sg3_utils is a package of utilities that send SCSI commands to the given
+\fIDEVICE\fR via a SCSI pass through interface provided by the host
+operating system. Some utilities, mainly those decoding structured data
+returned by SCSI commands (e.g. sg_vpd) can optionally provide JSON
+output, rather than simple, human-readable output. The default remains
+human-readable output.
+.PP
+JSON is an open standard file format that can be used for data exchange
+between systems. See https://en.wikipedia.org/wiki/JSON . JSON comes in
+many flavours and this one uses the json-builder C implementation found
+at https://github.com/json-parser/json-builder which implements four simple
+JSON data types: string, integer, boolean and null. Its other data types
+are JSON object and JSON array. This project uses the "snake" convention
+for JSON object names: all in lower case with separate words joined with
+a single underscore (e.g. "starting_lba"). The json-builder library uses
+the SPDX-License-Identifier: BSD-2-Clause which is the same license as the
+bulk of the utilities in the sg3_utils package.
+.PP
+The json-builder library is relatively lightweight (700 lines of C code) and
+is "hidden" fully within the sg3_utils library so that its function interface
+and data types are not available (directly) to the utilities in the sg3_utils
+package. That is why the json-builder interface (a file named
+sg_json_builder.h) is in the lib directory and not in the include directory.
+As presented on github, json-builder shares some header files with its
+companion json-parser. The author has modified the json-builder header to
+include what is needed from the json-parser header so that only the builder
+and not the parser are built. The parser could be added later, but currently
+there seems to be no need for it.
+.PP
+The user interface to JSON functionality in the sg3_utils package is heavily
+based on what has been done by Christian Franke and others in smartctl, a
+utility in the smartmontools package for getting S.M.A.R.T. information
+from disks (and other storage devices).
+.PP
+This manpage discusses the \fI\-\-json\fR option which may or may not itself
+have an optional argument. In its shorter form it may either be \fI\-j\fR or
+\fI\-J\fR (lower case preferred if not already in use). The shorter form may
+also take an argument but there must not be a space (or whitespace) between
+\fI\-j\fR and that argument.  
+.SH ENVIRONMENT VARIABLES
+The SG3_UTILS_JSON_OPTS environment variable
+yyyyyyyy
+ is explained in the previous
+section. It is only for backward compatibility of the command line options
+for older utilities.
+.PP
+The SG3_UTILS_DSENSE environment variable may be set to a number. It is
+only used by the embedded SNTL within the library used by the utilities in
+this library. SNTL is a SCSI to NVMe Translation Layer. This environment
+variable defaults to 0 which will lead to any utility that issues a SCSI
+command that is translated to a NVMe command (by the embedded SNTL) that
+fails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this
+variable is non\-zero then then the returned SCSI sense will be in 'descriptor'
+format.
+.PP
+Several utilities have their own environment variable setting (e.g.
+sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man pages
+for more information.
+.PP
+There is a Linux specific environment variable called SG3_UTILS_LINUX_NANO
+that if defined and the sg driver in the system is 4.0.30 or later, will
+show command durations in nanoseconds rather than the default milliseconds.
+Command durations are typically only shown if \-\-verbose is used 3 or more
+times. Due to an interface problem (a 32 bit integer that should be 64 bits
+with the benefit of hindsight) the maximum duration that can be represented
+in nanoseconds is about 4.2 seconds. If longer durations may occur then
+don't define this environment variable (or undefine it).
+.SH OPTIONS
+Since the argument to \fI\-\-json[=JO]\fR is optional, in the shorter form
+there can be no space(s) between the option and its argument.
+.TP
+\fB\-j[JO]\fR, \fB\-\-json\fR\fI[=JO]\fR
+yyyyyyyyy
+utilities that can cause lots of user data to be lost or overwritten
+sometimes have a \fI\-\-dry\-run\fR option. Device modifying actions are
+typically bypassed (or skipped) to implement a policy of "do no harm".
+This allows complex command line invocations to be tested before the
+action required (e.g. format a disk) is performed. The \fI\-\-dry\-run\fR
+option has become a common feature of many command line utilities (e.g.
+the Unix 'patch' command), not just those from this package.
+.br
+Note that most hyphenated option names in this package also can be given
+with an underscore rather than a hyphen (e.g.  \fI\-\-dry_run\fR).
+.SH WEB SITE
+There is a web page discussing this package at
+https://sg.danny.cz/sg/sg3_utils.html . The device naming used by this
+package on various operating systems is discussed at:
+https://sg.danny.cz/sg/device_name.html . There is a git code mirror at
+https://github.com/hreinecke/sg3_utils . The principle code repository
+uses subversion and is on the author's equipment. The author keeps track
+of this via the subversion revision number which is an ascending integer
+(currently at 922 for this package). The github mirror gets updated
+periodically from the author's repository. Depending on the time of
+update, the above Downloads section at sg.danny.cz may be more up to
+date than the github mirror.
+.SH AUTHORS
+Written by Douglas Gilbert. Some utilities have been contributed, see the
+CREDITS file and individual source files (in the 'src' directory).
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 2022 Douglas Gilbert
+.br
+Some utilities are distributed under a GPL version 2 license while
+others, usually more recent ones, are under a FreeBSD license. The files
+that are common to almost all utilities and thus contain the most reusable
+code, namely sg_lib.[hc], sg_cmds_basic.[hc] and sg_cmds_extra.[hc] are
+under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY
+or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg3_utils(sg3_utils), smartctl(smartmontools)