diff options
Diffstat (limited to 'doc')
-rw-r--r-- | doc/sg3_utils.8 | 24 | ||||
-rw-r--r-- | doc/sg3_utils_json.8 | 185 | ||||
-rw-r--r-- | doc/sg_get_elem_status.8 | 6 | ||||
-rw-r--r-- | doc/sg_get_lba_status.8 | 6 | ||||
-rw-r--r-- | doc/sg_opcodes.8 | 4 | ||||
-rw-r--r-- | doc/sg_rep_zones.8 | 6 | ||||
-rw-r--r-- | doc/sg_vpd.8 | 12 |
7 files changed, 171 insertions, 72 deletions
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8 index 5f4c8456..c210ccae 100644 --- a/doc/sg3_utils.8 +++ b/doc/sg3_utils.8 @@ -1,12 +1,13 @@ -.TH SG3_UTILS "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG3_UTILS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg3_utils \- a package of utilities for sending SCSI commands .SH SYNOPSIS .B sg_* [\fI\-\-dry\-run\fR] [\fI\-\-enumerate\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] -[\fI\-\-in=FN\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR] -[\fI\-\-timeout=SECS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] -[\fIOTHER_OPTIONS\fR] \fIDEVICE\fR +[\fI\-\-in=FN\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO]\fR] +[\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR] [\fI\-\-timeout=SECS\fR] +[\fI\-\-verbose\fR] [\fI\-\-version\fR] +[\fIOTHER_OPTIONS\fR] [\fIDEVICE\fR] .SH DESCRIPTION .\" Add any additional description here .PP @@ -616,6 +617,17 @@ expected in the contents of file: \fIFN\fR. Alternatively the short form option may be \fI\-I\fR or \fI\-X\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section below for more information. .TP +\fB\-\-json\fR[=\fIJO\fR] +The default output of most utilities that decode information returned from +SCSI devices is designed for human readability. Sometimes a more parseable +form of output is required and JSON is a popular way to do this. Only +utilities that decode a significant amount of SCSI data support this option. +.br +The corresponding short option is usually \fI\-j[JO]\fR but maybe +\fI\-J[JO]\fR if \fI\-j\fR is already in use. Note that in all cases \fIJO\fR +argument is itself optional. See the sg3_utils_json manpage for more +information. +.TP \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR several important SCSI commands (e.g. INQUIRY and MODE SENSE) have response lengths that vary depending on many factors, only some of which these @@ -848,8 +860,8 @@ 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 sg_decode_sense(sg3_utils), sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), -.B dmesg(1), mt(1) +.B sg3_utils_json,sg_decode_sense(sg3_utils), sdparm(sdparm), ddpt(ddpt), +.B lsscsi(lsscsi), dmesg(1), mt(1) .br The format of this section is: <utility_name>(<package_containing_utility>) or <utility_name>(<manpage_section_number_containing_utility>) . diff --git a/doc/sg3_utils_json.8 b/doc/sg3_utils_json.8 index 5fe989c8..8ada8146 100644 --- a/doc/sg3_utils_json.8 +++ b/doc/sg3_utils_json.8 @@ -1,9 +1,9 @@ -.TH SG3_UTILS "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG3_UTILS "8" "July 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 +\fI\-\-json[=JO]\fR [\fIOTHER_OPTIONS\fR] [\fIDEVICE\fR] .SH DESCRIPTION .\" Add any additional description here .PP @@ -47,61 +47,144 @@ have an optional argument. In its shorter form it may either be \fI\-j\fR or 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). +The SG3_UTILS_JSON_OPTS environment variable allows the user to override the +default values of the \fIJO\fR settings. Those settings can again be overridden +by the command line \fI\-\-json[=JO]\fR option. If the string associated with +SG3_UTILS_JSON_OPTS cannot be parsed this error message is sent to +stderr: "error parsing SG3_UTILS_JSON_OPTS environment variable, ignore". .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. +\fIJO\fR is a string of 0 or more characters whose order is not significant +apart from the negation characters ('\-' is preferred). The negation character +must appear immediately before the (boolean) feature it is toggling. +.br +In the short form the option letter may be other than \fI\-j\fR if that letter +has already been used (\fI\-J\fR is preferred next). For example the sg_ses +utility uses \fI\-j\fR for its "join" operation. Also since the argument to +the short form option is itself optional, there can be no space between the +short form option and \fIJO\fR, if it is given. To make this read a little +better on the command line, "=" may be first character of \fIJO\fR, so for +example, this is valid '\-j=av'. +.SH JSON CONTROL CHARACTERS +Each \fIJO\fR string is made up of zero or more of the following JSON control +characters. +.TP +\fB0\fR +If pretty printing JSON output, tab to 2 spaces. +.TP +\fB2\fR +If pretty printing JSON output, tab to 2 spaces. +.TP +\fB4\fR +If pretty printing JSON output, tab to 4 spaces. +.br +This is the default tab setting for pretty printing JSON. +.TP +\fB8\fR +If pretty printing JSON output, tab to 8 spaces. +.TP +\fB=\fR +does nothing. May appear as first character of \fIJO\fR. This character is +defined to make the short option form look better (e.g. '\-j=av'). +.TP +\fB\-\fR +negation character. Toggles the (boolean) sense of the following control +character. +.TP +\fBa\fR +this is a boolean control character for "abbreviated name expansion". T10 +names fields often depending on the amount of space available in the +CDB (command descriptor block) table in the relevant specification. This +leads to some clear names (e.g. "number of blocks) and some not so clear +names (e.g. "SKSV"). When this character is on (true), then fields that have +abbreviated names (subjective decision by author) will use the T10 field +name with a sub\-object containing at least a "i" field with the integer +value and a "abbreviated_name_expansion" field with a string value that +should make the T10 name clearer (e.g. "Sense Key Specific Valid"). +.br +This boolean control character is default off (false). +.TP +\fBe\fR +this is a boolean control character for "exit status". If active an "exit +status" field is placed at the end of the JSON output. The integer value +of this field is the Unix exit status value that is return to the operating +system when this utility exits. The value of 0 is a good exit (i.e. no +errors detected). +.br +This boolean control character is default on (true). +.TP +\fBh\fR +this is a boolean control character for "hexadecimal". Many values associated +with SCSI are best (or at least historically) viewed in hexadecimal while +JSON output prefers decimal integers (assumed to have a maximum size of 64 +bits, signed). The maximum size of most SCSI fields is 64 bit _unsigned_ . +Also some SCSI fields are masks which are best viewed in hex. When this +control character is active most (non\-trivial) fields that have an integer +value instead receive a a sub\-object containing at least a "i" field with +the integer value and a "hex" field with the corresponding hex value in a +JSON string. That hex string has no hex decorations (i.e. no leading '0x' +nor traing 'h'). +.br +This boolean control character is default off (false). +.TP +\fBl\fR +this is a boolean control character to control whether lead\-in fields are +output. Lead\-in fields are at the start of the JSON output and include +json_format_version and utility_invoked sub\-objects. The utility_invoked +sub\-object includes name, version_date string fields and an JSON array +named argv with an entry for each command line argument. If the \fIo\fR +control character is also active, then if available, the non_JSON output +is placed in and array called output with one element per line +of 'normal' output. +.br +This boolean control character is default on (true). +.TP +\fBo\fR +this is a boolean control character to control whether normal (i.e. +non\-JSON) lines of output are placed in a JSON array (one element per +line of normal output) within the utility_invoked subject (see control +character \fIl\fR). This control character is only active when the +\fIl\fR control character is also active). +.br +This boolean control character is default off (false). +.TP +\fBp\fR +this boolean control character controls whether the JSON output +is "pretty printed" or sent in a relatively compact stream suitable +for more efficient transmission over a communications channel. +.br +The pretty printed form of output has one JSON name with its associated +integer, string or boolean value per line; and one array element per line. +JSON objects and arrays that have an associated JSON object as their value, +have their name on a separate line. These lines are indented with the +current tab setting to indicate the level of nesting. Basically the pretty +printed form is for human consumption. +.br +This boolean control character is default on (true). +.TP +\fBs\fR +this boolean control character controls whether T10 field values that have +a defined meaning are broken out with an added JSON sub\-object usually +named "meaning". When active the field name has a sub\-object that contains +at least an "i" field with the integer value of the field and a JSON string +object, usually named "meaning", with a string that corresponds to the T10 +defined meaning of the value in the "i" field. +.br +This boolean control character is default on (true). +.TP +\fBv\fR +this is an integer control character that controls the amount of debug output. +It can be given multiple times to increase the level of JSON debug +verbosity in the output. +.br +Note that this verbose control character is JSON specific while the +\fI\-\-verbose\fR option (short form: fI\-v\fR often repeated: fI\-vvv\fR) that +most utilities support is more general. .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. +This integer control character is set to 0 by default. .SH AUTHORS Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and individual source files (in the 'src' directory). diff --git a/doc/sg_get_elem_status.8 b/doc/sg_get_elem_status.8 index 818d70e4..b9d7da11 100644 --- a/doc/sg_get_elem_status.8 +++ b/doc/sg_get_elem_status.8 @@ -1,4 +1,4 @@ -.TH SG_GET_ELEM_STATUS "8" "May 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_GET_ELEM_STATUS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_get_elem_status \- send SCSI GET PHYSICAL ELEMENT STATUS command .SH SYNOPSIS @@ -73,7 +73,7 @@ also given then the contents of \fIFN\fR are treated as binary. .TP \fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] output is in JSON format instead of human readable form. This is an -EXPERIMENTAL feature; more information to follow. +EXPERIMENTAL feature; see the sg3_utils_json manpage. .TP \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR where \fILEN\fR is the (maximum) response length in bytes. It is placed in @@ -134,4 +134,4 @@ Copyright \(co 2019\-2022 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" -.B sg_get_lba_status(8), sg3_utils(8) +.B sg_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils) diff --git a/doc/sg_get_lba_status.8 b/doc/sg_get_lba_status.8 index b9fe7c18..42288c4c 100644 --- a/doc/sg_get_lba_status.8 +++ b/doc/sg_get_lba_status.8 @@ -1,4 +1,4 @@ -.TH SG_GET_LBA_STATUS "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_GET_LBA_STATUS "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_get_lba_status \- send SCSI GET LBA STATUS(16 or 32) command .SH SYNOPSIS @@ -88,7 +88,7 @@ the contents of \fIFN\fR are treated as binary. .TP \fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] output is in JSON format instead of human readable form. This is an -EXPERIMENTAL feature; more information to follow. +EXPERIMENTAL feature; see sg3_utils_json manpage. .TP \fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR where \fILBA\fR is the starting Logical Block Address (LBA) to check the @@ -158,4 +158,4 @@ Copyright \(co 2009\-2022 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" -.B sg_write_same(8), sg_unmap(8), sg3_utils(8) +.B sg_write_same,sg_unmap,sg3_utils,sg3_utils_json(sg3_utils) diff --git a/doc/sg_opcodes.8 b/doc/sg_opcodes.8 index d3305589..f4ea0cbf 100644 --- a/doc/sg_opcodes.8 +++ b/doc/sg_opcodes.8 @@ -95,7 +95,7 @@ also given then the contents of \fIFN\fR are treated as binary. .TP \fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] output is in JSON format instead of human readable form. This is an -EXPERIMENTAL feature; more information to follow. +EXPERIMENTAL feature; see the sg3_utils_json manpage. .TP \fB\-m\fR, \fB\-\-mask\fR additionally prints out the cdb mask in hex. So a 12 byte cdb will have @@ -336,4 +336,4 @@ Copyright \(co 2004\-2022 Douglas Gilbert This software is distributed under the GPL version 2. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" -.B sg_inq(sg3_utils) +.B sg_inq,sg3_utils_json(sg3_utils) diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8 index 312bb611..71d101bc 100644 --- a/doc/sg_rep_zones.8 +++ b/doc/sg_rep_zones.8 @@ -1,4 +1,4 @@ -.TH SG_REP_ZONES "8" "April 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_REP_ZONES "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_rep_zones \- send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command .SH SYNOPSIS @@ -104,7 +104,7 @@ option for decoding the other two commands. .TP \fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] output is in JSON format instead of human readable form. This is an -EXPERIMENTAL feature; more information to follow. +EXPERIMENTAL feature; see the sg3_utils_json manpage. .TP \fB\-l\fR, \fB\-\-locator\fR=\fILBA\fR where \fILBA\fR plays a similar role as it does in \fI\-\-start=LBA\fR. @@ -210,5 +210,5 @@ Copyright \(co 2014\-2022 Douglas Gilbert This software is distributed under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. .SH "SEE ALSO" -.B sg_reset_wp,sg_zone(sg3_utils), +.B sg_reset_wp,sg_zone,sg3_utils_json(sg3_utils), .B zbd(libzbd), blkzone(util-linux) diff --git a/doc/sg_vpd.8 b/doc/sg_vpd.8 index 5bf6e893..53dd1808 100644 --- a/doc/sg_vpd.8 +++ b/doc/sg_vpd.8 @@ -1,13 +1,13 @@ -.TH SG_VPD "8" "January 2022" "sg3_utils\-1.48" SG3_UTILS +.TH SG_VPD "8" "July 2022" "sg3_utils\-1.48" SG3_UTILS .SH NAME sg_vpd \- fetch SCSI VPD page and/or decode its response .SH SYNOPSIS .B sg_vpd [\fI\-\-all\fR] [\fI\-\-enumerate\fR] [\fI\-\-examine\fR] [\fI\-\-force\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-ident\fR] [\fI\-\-inhex=FN\fR] -[\fI\-\-long\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-page=PG\fR] [\fI\-\-quiet\fR] -[\fI\-\-raw\fR] [\fI\-\-vendor=VP\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] -[\fIDEVICE\fR] +[\fI\-\-json[=JO]\fR] [\fI\-\-long\fR] [\fI\-\-maxlen=LEN\fR] +[\fI\-\-page=PG\fR] [\fI\-\-quiet\fR] [\fI\-\-raw\fR] [\fI\-\-vendor=VP\fR] +[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fIDEVICE\fR] .SH DESCRIPTION .\" Add any additional description here .PP @@ -118,6 +118,10 @@ byte each of which is whitespace or comma separated. Anything from and including a hash mark to the end of line is ignored. If the \fI\-\-raw\fR option is also given then \fIFN\fR is treated as binary. .TP +\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR] +output is in JSON format instead of human readable form. This is an +EXPERIMENTAL feature; see sg3_utils_json manpage. +.TP \fB\-l\fR, \fB\-\-long\fR when decoding some VPD pages, give a little more output. For example the ATA Information VPD page only shows the signature (in hex) and the IDENTIFY |