7 files changed, 184 insertions, 29 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 22e659e7..3cb12ebf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -14,7 +14,7 @@ man_MANS = \
 	sg_ses.8 sg_ses_microcode.8 sg_start.8 sg_stpg.8 sg_stream_ctl.8 \
 	sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 sg_vpd.8 \
 	sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 sg_write_same.8 \
-	sg_write_verify.8 sg_write_x.8 sg_zone.8
+	sg_write_verify.8 sg_write_x.8 sg_zone.8 sg_z_act_query.8
 CLEANFILES =
 
 if OS_LINUX
diff --git a/doc/Makefile.in b/doc/Makefile.in
index cce580f0..c1e2bdbd 100644
--- a/doc/Makefile.in
+++ b/doc/Makefile.in
@@ -301,7 +301,8 @@ man_MANS = scsi_mandat.8 scsi_readcap.8 scsi_ready.8 scsi_satl.8 \
 	sg_sync.8 sg_timestamp.8 sg_turs.8 sg_unmap.8 sg_verify.8 \
 	sg_vpd.8 sg_wr_mode.8 sg_write_buffer.8 sg_write_long.8 \
 	sg_write_same.8 sg_write_verify.8 sg_write_x.8 sg_zone.8 \
-	$(am__append_1) $(am__append_3) $(am__append_5)
+	sg_z_act_query.8 $(am__append_1) $(am__append_3) \
+	$(am__append_5)
 CLEANFILES = $(am__append_2) $(am__append_4) $(am__append_6)
 all: all-am
 
diff --git a/doc/sg3_utils.8 b/doc/sg3_utils.8
index 5fcbf759..abe07d82 100644
--- a/doc/sg3_utils.8
+++ b/doc/sg3_utils.8
@@ -1,4 +1,4 @@
-.TH SG3_UTILS "8" "November 2021" "sg3_utils\-1.47" SG3_UTILS
+.TH SG3_UTILS "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg3_utils \- a package of utilities for sending SCSI commands
 .SH SYNOPSIS
@@ -34,8 +34,8 @@ of the diagram. The highest level (i.e. most abstract) document is the SCSI
 Architecture Model (SAM) with SAM\-5 being the most recent standard (ANSI
 INCITS 515\-2016) with the most recent draft being SAM\-6 revision 4 . SCSI
 commands in common with all device types can be found in SCSI Primary
-Commands (SPC) of which SPC\-4 is the most recent standard (ANSI INCITS
-513-2015). The most recent SPC draft is SPC\-5 revision 21. Block device
+Commands (SPC) of which SPC\-5 is the most recent standard (ANSI INCITS
+502-2020). The most recent SPC draft is SPC\-6 revision 6. Block device
 specific commands (e.g. as used by disks) are in SBC, those for tape drives
 in SSC, those for SCSI enclosures in SES and those for CD/DVD/BD drives in
 MMC.
@@ -64,7 +64,7 @@ options can be elided, for example: '\-all' is equivalent to '\-a \-l \-l'.
 The \fIDEVICE\fR argument may appear after, between or prior to any options.
 .PP
 The older utilities, including as sg_inq, sg_logs, sg_modes, sg_opcode,
-sg_rbuff,  sg_readcap, sg_senddiag, sg_start and sg_turs had individual
+sg_rbuff, sg_readcap, sg_senddiag, sg_start and sg_turs had individual
 command line processing code typically based on a single "\-" followed by one
 or more characters. If an argument is needed then it follows a "=" (
 e.g. '\-p=1f' in sg_modes with its older interface). Various options can be
@@ -575,10 +575,14 @@ option requests hexadecimal output. In these cases the '\-?' option will
 output the usage message then exit.
 .TP
 \fB\-H\fR, \fB\-\-hex\fR
-for SCSI commands that yield a non\-trivial response, print out that
-response in ASCII hexadecimal. To produce hexadecimal that can be parsed
-by other utilities (e.g. without a relative address to the left and without
-trailing ASCII) use this option three or four times.
+for SCSI commands that yield a non\-trivial response, print out that response
+in ASCII hexadecimal. When used once, 16 bytes are printed on each line,
+prefixed by an relative address, starting at 0 (hex). When used twice, an
+ASCII rendering of the 16 bytes is appended to each line, with non printeble
+characters replaced by a '.' . When used three times only the 16 hex bytes
+are printed on each line (hence no address prefix nor ASCII appended). To
+produce hexadecimal that can be parsed by other utilities use this option
+three or four times.
 .TP
 \fB\-i\fR, \fB\-\-in\fR=\fIFN\fR
 many SCSI commands fetch a significant amount of data (returned in the
@@ -744,6 +748,12 @@ containing a hash mark ('#') is ignored from that point until the end of that
 line. Users are encouraged to use hash marks to introduce comments in hex
 files. The author uses the extension'.hex' on such files. Examples can be
 found in the 'inhex' directory.
+.PP
+The hexadecimal format described in the previous paragraph can be converted
+to binary using the sg_decode_sense utility with these
+options: "\fI\-\-inhex=HFN \-\-nodecode \-\-write=WFN\fR". The input (in
+hex) is in the \fIHFN\fR file while the output is placed in the \fIWFN\fR
+file.
 .SH MICROCODE AND FIRMWARE
 There are two standardized methods for downloading microcode (i.e. device
 firmware) to a SCSI device. The more general way is with the SCSI WRITE
@@ -777,7 +787,7 @@ 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 774 for this package). The github mirror gets updated
+(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.
@@ -796,4 +806,5 @@ 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 sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
+.B sg_decode_sense(sg3_utils), sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi),
+.B dmesg(1), mt(1)
diff --git a/doc/sg_decode_sense.8 b/doc/sg_decode_sense.8
index 62d4c548..7c952ed0 100644
--- a/doc/sg_decode_sense.8
+++ b/doc/sg_decode_sense.8
@@ -1,18 +1,18 @@
-.TH SG_DECODE_SENSE "8" "November 2021" "sg3_utils\-1.47" SG3_UTILS
+.TH SG_DECODE_SENSE "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_decode_sense \- decode SCSI sense and related data
 .SH SYNOPSIS
 .B sg_decode_sense
 [\fI\-\-binary=BFN\fR] [\fI\-\-cdb\fR] [\fI\-\-err=ES\fR] [\fI\-\-file=HFN\fR]
-[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR] [\fI\-\-nospace\fR]
-[\fI\-\-status=SS\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
-[\fI\-\-write=WFN\fR] [H1 H2 H3 ...]
+[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR] [\fI\-\-nodecode\fR]
+[\fI\-\-nospace\fR] [\fI\-\-status=SS\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] [\fI\-\-write=WFN\fR] [H1 H2 H3 ...]
 .SH DESCRIPTION
 .\" Add any additional description here
-This utility takes SCSI sense data in binary or as a sequence of
-ASCII hexadecimal bytes and decodes it. The primary reference for the
-decoding is SPC\-4 ANSI INCITS 513\-2015 and the most recent draft
-SPC\-5 revision 19 which can be found at https://www.t10.org and other
+This utility takes SCSI sense data in binary or as a sequence of ASCII
+hexadecimal bytes and decodes it. The primary reference for the
+decoding is SPC\-5 ANSI INCITS 502\-2020 and the most recent draft
+SPC\-6 revision 6 which can be found at https://www.t10.org and other
 locations on the internet.
 .PP
 SCSI sense data is often found in kernel log files as a result of
@@ -74,15 +74,23 @@ decoded from pairs of ASCII hexadecimal digits.
 output the usage message then exit.
 .TP
 \fB\-H\fR, \fB\-\-hex\fR
-this option is used in conjunction with \fI\-\-write=WFN\fR in order to
+this option is used once in conjunction with \fI\-\-write=WFN\fR in order to
 change the output written to \fIWFN\fR to lines of ASCII hex bytes suitable
 for a C language compiler. Each line contains up to 16 bytes (e.g. a line
 starting with "0x3b,0x07,0x00,0xff").
+.br
+In other cases (i.e. when \fI\-\-write=WFN\fR is not given, or this option
+is given more than once) then the output is as described in the sg3_utils(8)
+manpage.
 .TP
 \fB\-i\fR, \fB\-\-inhex\fR=\fIHFN\fR
 same action as \fI\-\-file=HFN\fR. This option was added for compatibility
 with other utilities in this package that have a \fI\-\-inhex=\fR option.
 .TP
+\fB\-N\fR, \fB\-\-nodecode\fR
+Do not decode the given data as sense or a cdb. Useful when arbitrary data
+is given (e.g. when converting hex to binary).
+.TP
 \fB\-n\fR, \fB\-\-nospace\fR
 expect ASCII hexadecimal to be a string of hexadecimal digits with no
 spaces between them. Bytes are decoded by taking two hexadecimal digits
@@ -121,6 +129,15 @@ data.
 The sg_raw utility takes a ASCII hexadecimal sequence representing a SCSI
 CDB. When sg_raw is given the '\-vvv' option, it will attempt to decode the
 CDB name.
+.PP
+Using the option combination: "\fI\-\-inhex=HFN \-\-nodecode \-\-write=WFN\fR"
+may be used to convert hexadecimal (as produced by this and other utilities
+in this package) to binary where the output file is \fIWFN\fR.
+.PP
+Unlike many other utilities there is no \fI\-\-raw\fR option. However binary
+data can be input using the \fI\-\-binary=BFN\fR option while binary data
+can be output using the \fI\-\-write=WFN\fR option (in the absence of the
+\fI\-\-hex\fR option).
 .SH EXAMPLES
 Sense data is often printed out in kernel logs and sometimes on the
 command line when verbose or debug flags are given. It will be at least
diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8
index bd25fa45..d438971e 100644
--- a/doc/sg_rep_zones.8
+++ b/doc/sg_rep_zones.8
@@ -1,13 +1,13 @@
-.TH SG_REP_ZONES "8" "June 2021" "sg3_utils\-1.47" SG3_UTILS
+.TH SG_REP_ZONES "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_rep_zones \- send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command
 .SH SYNOPSIS
 .B sg_rep_zones
-[\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
+[\fI\-\-domain\fR] [\fI\-\-force\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
@@ -33,6 +33,12 @@ Arguments to long options are mandatory for short options as well.
 \fB\-d\fR, \fB\-\-domain\fR
 send or decode the SCSI REPORT ZONE DOMAINS command.
 .TP
+\fB\-f\fR, \fB\-\-force\fR
+when decoding the response to this command, certain sanity checks are
+done and if they fail a message is sent to stderr and a non\-zero
+exit status is set. If this option is given those sanity checks are
+bypassed.
+.TP
 \fB\-h\fR, \fB\-\-help\fR
 output the usage message then exit.
 .TP
diff --git a/doc/sg_z_act_query.8 b/doc/sg_z_act_query.8
new file mode 100644
index 00000000..a43ad073
--- /dev/null
+++ b/doc/sg_z_act_query.8
@@ -0,0 +1,115 @@
+.TH SG_Z_ACT_QUERY "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS
+.SH NAME
+sg_z_act_query \- send a SCSI ZONE ACTIVATE or ZONE QUERY command
+.SH SYNOPSIS
+.B sg_z_act_query
+[\fI\-\-activate\fR] [\fI\-\-all\fR] [\fI\-\-force\fR] [\fI\-\-help\fR]
+[\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-maxlen=LEN\fR]
+[\fI\-\-num=ZS\fR] [\fI\-\-other=ZDID\fR] [\fI\-\-query\fR] [\fI\-\-raw\fR]
+[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-zone=ID\fR]
+\fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Sends a SCSI ZONE ACTIVATE or ZONE QUERY command to the \fIDEVICE\fR. If the
+\fI\-\-activate\fR option is not given, then a ZONE QUERY command is sent.
+These commands where added in the ZBC\-2 draft revision 4 (zbc2r04.pdf).
+.PP
+Both of these commands have similar cdb_s and responses hence they are both
+placed in this utility. The difference is that only the ZONE ACTIVATE command
+will potentially activate or deactivate zones. Both commands will perform
+a "Verify activations operation" as defined in ZBC\-2 .
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-A\fR, \fB\-\-activate\fR
+sends a ZONE ACTIVATE command to the \fIDEVICE\fR. The default (i.e. without
+this option) is to send a ZONE QUERY command.
+.TP
+\fB\-a\fR, \fB\-\-all\fR
+sets the ALL field in the cdb.
+.TP
+\fB\-f\fR, \fB\-\-force\fR
+when decoding the response to this command, certain sanity checks are
+done and if they fail a message is sent to stderr and a non\-zero
+exit status is set. If this option is given those sanity checks are
+bypassed.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-H\fR, \fB\-\-hex\fR
+output the response in hexadecimal to stdout. When used once the whole
+response is output in ASCII hexadecimal with a leading address (starting at
+0) on each line. When used twice each zone activation 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
+By default it is assumed the response is from a ZONE QUERY command but
+that shouldn't matter because the response of the ZONE ACTIVATE and
+ZONE QUERY commands is of the same form.
+.TP
+\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
+where \fILEN\fR is the (maximum) response length in bytes. It is placed in
+the cdb's "allocation length" field. If not given (or \fILEN\fR is zero)
+then 8192 is used. The maximum allowed value of \fILEN\fR is 1048576.
+.br
+The draft standard disallows allocation lengths less than 64.
+.TP
+\fB\-n\fR, \fB\-\-num\fR=\fIZS\fR
+where \fIZS\fR is placed in the "Number of zones" field in the cdb. This
+option is usually ignored if the \fI\-\-all\fR option is given. If the
+\fI\-\-all\fR option is not given, the default value of this field is 1 .
+.TP
+\fB\-o\fR, \fB\-\-other\fR=\fIZDID\fR
+where the \fIZDID\fR value will be placed in the "Other zone domain ID"
+field of the cdb to be sent to the \fIDEVICE\fR.
+.TP
+\fB\-q\fR, \fB\-\-query\fR
+causes the ZONE QUERY command to be sent to the \fIDEVICE\fR. Since this
+is the default action, this option is typically not needed. If both this
+option and the \fI\-\-activate\fR option are given, an error will be
+reported (and no command will be sent).
+.TP
+\fB\-r\fR, \fB\-\-raw\fR
+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\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.TP
+\fB\-z\fR, \fB\-\-zone\fR=\fIID\fR
+where \fIID\fR is placed in the cdb's ZONE ID field. A zone id is a zone
+start logical block address (LBA). The default value is 0. \fIID\fR is
+assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'
+which indicate hexadecimal. The maximum value that can be given is
+2^64 - 2. In the unlikely event of wanting to give 2^64 - 1, enter "\-1".
+.SH EXIT STATUS
+The exit status of sg_z_act_query is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written by Douglas Gilbert.
+.SH "REPORTING BUGS"
+Report bugs to <dgilbert at interlog dot com>.
+.SH COPYRIGHT
+Copyright \(co 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.
+.SH "SEE ALSO"
+.B sg_zone,sg_rep_zones,sg_reset_wp(sg3_utils)
diff --git a/doc/sg_zone.8 b/doc/sg_zone.8
index bc916423..cf35c16c 100644
--- a/doc/sg_zone.8
+++ b/doc/sg_zone.8
@@ -1,4 +1,4 @@
-.TH SG_ZONE "8" "January 2021" "sg3_utils\-1.43" SG3_UTILS
+.TH SG_ZONE "8" "November 2021" "sg3_utils\-1.48" SG3_UTILS
 .SH NAME
 sg_zone \- send a SCSI ZONE modifying command
 .SH SYNOPSIS
@@ -18,6 +18,11 @@ was added in zbc2r01b.
 .PP
 One and only one of the \fI\-\-open\fR, \fI\-\-close\fR, \fI\-\-finish\fR,
 \fI\-\-remove\fR and \fI\-\-sequentialize\fR options can be chosen.
+.PP
+The REPORT ZONES, REPORT REALMS and REPORT ZONE DOMAINS commands may be
+accessed via the sg_rep_zones utility. The ZONE ACTIVATE and ZONE QUERY
+commands may be accessed via the sg_z_act_query utility. The RESET WRITE
+POINTER command may be accessed via the sg_reset_wp utility.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
@@ -78,4 +83,4 @@ Copyright \(co 2014\-2021 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_rep_zones,sg_reset_wp(sg3_utils)
+.B sg_rep_zones,sg_reset_wp,sg_z_act_query(sg3_utils)