sg3_utils.spec: change tarball extension from .tgz to .tar.gz ; fix build issue with Fedora 36; minor work

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

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