sg_zones: finish initial support for REPORT ZONE DOMAINS and REPORT REALMS

Lots of clean-up based on Coverity and other code checkers. Add some new
inhex folder entries to testing those new ZBC-2 commands.


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

2 files changed, 75 insertions, 21 deletions

diff --git a/doc/sg_get_elem_status.8 b/doc/sg_get_elem_status.8
index a4d533f2..27d9b2b5 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" "August 2019" "sg3_utils\-1.45" SG3_UTILS
+.TH SG_GET_ELEM_STATUS "8" "June 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
 sg_get_elem_status \- send SCSI GET PHYSICAL ELEMENT STATUS command
 .SH SYNOPSIS
@@ -20,7 +20,8 @@ to stdout.  The amount of output can be reduced by the \fI\-\-brief\fR option.
 .PP
 Rather than send this SCSI command to \fIDEVICE\fR, if the \fI\-\-inhex=FN\fR
 option is given, then the contents of the file named \fIFN\fR are decoded
-as ASCII hex and then processed if it was the response of this command.
+as ASCII hex (or binary if \fI\-\-raw\fR is also given) and then processed
+as if it was the response of this command.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
@@ -42,7 +43,7 @@ output the usage message then exit.
 output response to this command in ASCII hex.
 .TP
 \fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
-where \fIFN\fR is a function name whose contents are assumed to be ASCII
+where \fIFN\fR is a file name whose contents are assumed to be ASCII
 hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
 a warning is issued and the utility continues, decoding the file named
 \fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
@@ -92,7 +93,7 @@ Written by Douglas Gilbert.
 .SH "REPORTING BUGS"
 Report bugs to <dgilbert at interlog dot com>.
 .SH COPYRIGHT
-Copyright \(co 2019 Douglas Gilbert
+Copyright \(co 2019\-2021 Douglas Gilbert
 .br
 This software is distributed under a FreeBSD license. There is NO
 warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8
index 7d9c9a5d..bd25fa45 100644
--- a/doc/sg_rep_zones.8
+++ b/doc/sg_rep_zones.8
@@ -1,21 +1,38 @@
-.TH SG_REP_ZONES "8" "March 2021" "sg3_utils\-1.46" SG3_UTILS
+.TH SG_REP_ZONES "8" "June 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
-sg_rep_zones \- send SCSI REPORT ZONES command
+sg_rep_zones \- send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command
 .SH SYNOPSIS
 .B sg_rep_zones
-[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-num=NUM\fR]
-[\fI\-\-partial\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR]
+[\fI\-\-domain\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR]
+[\fI\-\-locator=LBA\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-num=NUM\fR]
+[\fI\-\-partial\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-realm\fR]
 [\fI\-\-report=OPT\fR] [\fI\-\-start=LBA\fR] [\fI\-\-verbose\fR]
 [\fI\-\-version\fR] [\fI\-\-wp\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
-Sends a SCSI REPORT ZONES command to \fIDEVICE\fR and outputs the data
-returned. This command is found in the ZBC draft standard, revision
-5 (zbc\-r05.pdf).
+Sends a SCSI REPORT ZONES, REPORT REALMS or REPORT ZONE DOMAINS command to
+\fIDEVICE\fR and decodes (or simply outputs) the data returned. These
+commands is found in the ZBC\-2 draft standard, revision 10 (zbc2r05.pdf).
+Only the REPORT ZONES command is defined in the original ZBC
+standard (INCITS 536\-2017) and it is the default.
+.PP
+The REPORT ZONE DOMAINS command will be sent (or decoded) when the
+\fI\-\-domain\fR option is given. The REPORT REALMS command will be
+sent (or decoded) when the \fI\-\-realm\fR option is given.
+.PP
+Rather than send a SCSI command to \fIDEVICE\fR, if the \fI\-\-inhex=FN\fR
+option is given, then the contents of the file named \fIFN\fR are decoded
+as ASCII hex (or binary if \fI\-\-raw\fR is also given) and then processed
+as if it was the response of the command. By default the REPORT ZONES
+command response is assumed; if the \fI\-\-domain\fR or \fI\-\-realm\fR
+option is given then the corresponding command response is assumed.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
+\fB\-d\fR, \fB\-\-domain\fR
+send or decode the SCSI REPORT ZONE DOMAINS command.
+.TP
 \fB\-h\fR, \fB\-\-help\fR
 output the usage message then exit.
 .TP
@@ -25,6 +42,26 @@ response is output in ASCII hexadecimal with a leading address (starting at
 0) on each line. When used twice each zone descriptor in the response is
 output separately in hexadecimal. When used thrice the whole response is
 output in hexadecimal with no leading address (on each line).
+.br
+The output format when this option is given thrice is suitable contents
+for a later invocation with the \fI\-\-inhex=FN\fR option.
+.TP
+\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
+where \fIFN\fR is a file name whose contents are assumed to be ASCII
+hexadecimal. If \fIDEVICE\fR is also given then \fIDEVICE\fR is ignored,
+a warning is issued and the utility continues, decoding the file named
+\fIFN\fR. See the "FORMAT OF FILES CONTAINING ASCII HEX" section in the
+sg3_utils manpage for more information. If the \fI\-\-raw\fR option is
+also given then the contents of \fIFN\fR are treated as binary.
+.br
+Note that by default this utility assumes then contents are the response
+from a REPORT ZONES command. Use the \fI\-\-domain\fR or \fI\-\-realm\fR
+option for decoding the other two commands.
+.TP
+\fB\-l\fR, \fB\-\-locator\fR=\fILBA\fR
+where \fILBA\fR plays a similar role as it does in \fI\-\-start=LBA\fR.
+It is the field name used in the REPORT REALMS and REPORT ZONE DOMAINS
+commands.
 .TP
 \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
 where \fILEN\fR is the (maximum) response length in bytes. It is placed in
@@ -40,29 +77,45 @@ descriptors returned by the REPORT ZONES command.
 set the PARTIAL bit in the cdb.
 .TP
 \fB\-r\fR, \fB\-\-raw\fR
-output the SCSI response (i.e. the data\-out buffer) in binary (to stdout).
+output response in binary (to stdout) unless the \fI\-\-inhex=FN\fR option
+is also given. In that case the input file name (\fIFN\fR) is decoded as
+binary (and the output is _not_ in binary (but may be hex)).
 .TP
 \fB\-R\fR, \fB\-\-readonly\fR
 open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
 The default is to open it read\-write.
 .TP
+\fB\-e\fR, \fB\-\-realm\fR
+send or decode the SCSI REPORT REALMS command.
+.TP
 \fB\-o\fR, \fB\-\-report\fR=\fIOPT\fR
 where \fIOPT\fR will become the contents of the REPORTING OPTION field
-in the cdb. The default value is 0 which means report a list of all zones.
-Some other values are 1 for list zones with a zone condition of empty; 2 for
-list zones with a zone condition of implicitly opened; 3 for list zones with
-a zone condition of explicitly opened; 4 for list zones with a zone condition
-of closed; 5 for list zones with a zone condition of full; 6 for list zones
-with a zone condition of read only; 7 for list zones with a zone condition of
-offline. Other values are 0x10 for list zones with RWP recommended set to
-true; 0x11 for list zones with non\-sequential write resource active set to
-true and 0x3f for list zones with a zone condition of not write pointer.
+in the cdb. The reporting options differ between REPORT ZONES, REPORT ZONE
+DOMAINS and REPORT REALMS. If the \fI\-\-help\fR option is given twice (
+or the equivalent '\-hh') a list of available reporting options (as of
+writing) for each command is output.
+.br
+The default value for REPORT ZONES is 0 which means report a list of all
+zones. Some other values are 1 for list zones with a zone condition of empty;
+2 for list zones with a zone condition of implicitly opened; 3 for list zones
+with a zone condition of explicitly opened; 4 for list zones with a zone
+condition of closed; 5 for list zones with a zone condition of full; 6 for
+list zones with a zone condition of read only; 7 for list zones with a zone
+condition of offline. Other values are 0x10 for list zones with 'RWP
+recommended' set to true; 0x11 for list zones with non\-sequential write
+resource active set to true and 0x3f for list zones with a zone condition
+of 'not write pointer'.
 .TP
 \fB\-s\fR, \fB\-\-start\fR=\fILBA\fR
 where \fILBA\fR is at the start or within the first zone to be reported. The
 default value is 0. If \fILBA\fR is not a zone start LBA then the preceding
 zone start LBA is used for reporting. Assumed to be in decimal unless
 prefixed with '0x' or has a trailing 'h' which indicate hexadecimal.
+.br
+The zone start LBA field used in the REPORT ZONES command was changed to
+the zone domain/realm locator field for the two newer ZBC\-2 commands. For
+this utility \fI\-\-locator=LBA\fR and \fI\-\-start=LBA\fR are
+interchangeable.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity, (i.e. debug output).