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

6 files changed, 133 insertions, 13 deletions

diff --git a/doc/rescan-scsi-bus.sh.8 b/doc/rescan-scsi-bus.sh.8
index c91b1f38..1533791d 100644
--- a/doc/rescan-scsi-bus.sh.8
+++ b/doc/rescan-scsi-bus.sh.8
@@ -1,4 +1,4 @@
-.TH RESCAN\-SCSI\-BUS.SH "1" "Aprile 2022" "rescan\-scsi\-bus.sh" "User Commands"
+.TH RESCAN\-SCSI\-BUS.SH "1" "May 2022" "rescan\-scsi\-bus.sh" "User Commands"
 .SH NAME
 rescan-scsi-bus.sh \- script to add and remove SCSI devices without rebooting
 .SH SYNOPSIS
@@ -43,7 +43,7 @@ flush failed multipath devices     [default: disabled]
 remove stale devices (DANGEROUS)
 .TP
 \fB\-\-forcerescan\fR
-remove and readd existing devices (DANGEROUS)
+remove and re\-add existing devices (DANGEROUS)
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 print usage message then exit
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)
diff --git a/doc/sg_dd.8 b/doc/sg_dd.8
index 14290e07..ffe8f13f 100644
--- a/doc/sg_dd.8
+++ b/doc/sg_dd.8
@@ -1,4 +1,4 @@
-.TH SG_DD "8" "August 2021" "sg3_utils\-1.47" SG3_UTILS
+.TH SG_DD "8" "May 2022" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_dd \- copy data to and from files and devices, especially SCSI
 devices
@@ -98,7 +98,7 @@ values are given, the first applies to \fIIFILE\fR while the second applies
 to \fIOFILE\fR. The value may be from 0 to 7 where 0 is the default and means
 there are no command duration limits. Command duration limits are only
 supported by 16 byte READ and WRITE commands (plus READ(32), WRITE(32) and
-the WRITE SCATTERED command, bit thay are used by this utility). If the
+the WRITE SCATTERED command, bit they are used by this utility). If the
 cdbsz operand is not given and would have a value less than 16, then if
 \fICDL\fR is greater than 0, the cdbsz is increased to 16.
 .br
@@ -581,7 +581,7 @@ Written by Douglas Gilbert and Peter Allworth.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2000\-2021 Douglas Gilbert
+Copyright \(co 2000\-2022 Douglas Gilbert
 .br
 This software is distributed under the GPL version 2. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
diff --git a/doc/sg_opcodes.8 b/doc/sg_opcodes.8
index e7a1f19d..d3305589 100644
--- a/doc/sg_opcodes.8
+++ b/doc/sg_opcodes.8
@@ -131,12 +131,12 @@ the \fIDEVICE\fR will be queried for the given operation code (i.e. the
 \fIOP\fR value) which is the first byte of a SCSI command. Optionally, if
 a \fISA\fR value is given, it will be used as that SCSI command's service
 action. Note that \fIOP\fR and \fIOP,0\fR are not the same thing, as SCSI
-does allow the service action to be 0 (but it is not comman). \fIOP\fR and
-\fISA\fR are decimal unless prefixed by "0x" or they have a trailing "h".
-\fIOP\fR should be in the range 0 to 255 (0xff) inclusive. \fISA\fR should
-be in the range 0 to 65535 (0xffff) inclusive. When this option is not
-given then all available SCSI commands supported by the \fIDEVICE\fR are
-listed.
+does allow the service action to be 0 (but not in this command). \fIOP\fR
+and \fISA\fR are decimal unless prefixed by "0x" or they have a
+trailing "h". \fIOP\fR should be in the range 0 to 255 (0xff) inclusive.
+\fISA\fR should be in the range 0 to 65535 (0xffff) inclusive. When this
+option is not given then all available SCSI commands supported by the
+\fIDEVICE\fR are listed.
 .TP
 \fB\-p\fR, \fB\-\-pdt\fR=\fIDT\fR
 where \fIDT\fR is the peripheral device type. This is used together with
diff --git a/doc/sg_referrals.8 b/doc/sg_referrals.8
index cabb8359..f1371794 100644
--- a/doc/sg_referrals.8
+++ b/doc/sg_referrals.8
@@ -36,7 +36,7 @@ the cdb's "allocation length" field. If not given then 256 is used. 256 is
 enough space for the response header and user data segment descriptors.
 .TP
 \fB\-s\fR, \fB\-\-one-segment\fR
-report the user data segment of the segment spefified by the \fILBA\fR
+report the user data segment of the segment specified by the \fILBA\fR
 parameter only.
 .TP
 \fB\-r\fR, \fB\-\-raw\fR
diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8
index 68fecee2..0f76ee4d 100644
--- a/doc/sg_rep_zones.8
+++ b/doc/sg_rep_zones.8
@@ -60,7 +60,7 @@ or the number of zones is exhausted.
 .br
 The \fIZT\fR numbers and abbreviations are listed when the \fI\-\-help\fR
 option is given twice. Warning: using '!' for inverting the condition may
-not be so practical as the shell (e.g. bash) may interprete '!' as having
+not be so practical as the shell (e.g. bash) may interpret '!' as having
 special meaning. Placing single quotes around \fIZT\fR fixes the problem
 for the bash shell (e.g. \-\-find='!c' meaning find the first zone whose
 type is not conventional).