diff options
author | Douglas Gilbert <dgilbert@interlog.com> | 2022-05-12 18:37:08 +0000 |
---|---|---|
committer | Douglas Gilbert <dgilbert@interlog.com> | 2022-05-12 18:37:08 +0000 |
commit | 404cd7cc68c42c49076623e3ec13bb1f42f74ec7 (patch) | |
tree | f164f678be7a236aeb87874e1fa6890b37c2c6b3 /doc | |
parent | 3e056f675f51f14a5209efe1b491ba897e7873ce (diff) | |
download | sg3_utils-404cd7cc68c42c49076623e3ec13bb1f42f74ec7.tar.gz |
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
Diffstat (limited to 'doc')
-rw-r--r-- | doc/rescan-scsi-bus.sh.8 | 4 | ||||
-rw-r--r-- | doc/sg3_utils_json.8 | 120 | ||||
-rw-r--r-- | doc/sg_dd.8 | 6 | ||||
-rw-r--r-- | doc/sg_opcodes.8 | 12 | ||||
-rw-r--r-- | doc/sg_referrals.8 | 2 | ||||
-rw-r--r-- | doc/sg_rep_zones.8 | 2 |
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). |