path: root/doc/sg_rep_zones.8

.TH SG_REP_ZONES "8" "January 2022" "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\-\-brief\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
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\-b\fR, \fB\-\-brief\fR
even though a ZBC disk will typically limit the size of the response
to the REPORT ZONES command (e.g. to 127 zones say), this is still
potentially a lot of output. This option will only decode and output
fields found in the header plus some of the fields from the last
descriptor in the current response.
.TP
\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
\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 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
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.
.TP
\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
where \fINUM\fR is the (maximum) number of zone descriptors to print out.
The default value is zero which is taken to mean print out all zone
descriptors returned by the REPORT ZONES command.
.TP
\fB\-p\fR, \fB\-\-partial\fR
set the PARTIAL bit in the cdb.
.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\-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 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).
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.TP
\fB\-w\fR, \fB\-\-wp\fR
print the write pointer (in hex) only. In the absence of errors, then a hex
LBA will be printed on each line, one line for each zone. Can be usefully
combined with the \fI\-\-num=NUM\fR and \fI\-\-start=LBA\fR options.
.SH EXIT STATUS
The exit status of sg_rep_zones 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 2014\-2022 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_reset_wp,sg_zone(sg3_utils)