path: root/doc/sg_rep_zones.8

.TH SG_REP_ZONES "8" "AUGUST 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\-\-find=ZT\fR] [\fI\-\-force\fR]
[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO\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\-\-statistics\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 are found in the ZBC\-2 draft standard, revision 12 (zbc2r12.pdf).
Only the REPORT ZONES command is defined in the original ZBC
standard (INCITS 536\-2017) and it is the default for this utility.
.PP
The REPORT ZONE DOMAINS command will be sent (and decoded) when the
\fI\-\-domain\fR option is given. The REPORT REALMS command will be
sent (and 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. due to the "allocation length" field), this may
still be potentially a lot of output. This option will only decode and
output fields found in the response header plus 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\-\-find\fR=\fIZT\fR
where \fIZT\fR is a zone type number or an abbreviation for a zone
type. If \fIZT\fR is prefixed by either '\-' or '!' then the check for
equality is inverted to be a check for inequality. IOWs it does a: find
the first occurrence that is
.B not
the given zone type.
.br
The algorithm used by this option takes into account the \fI\-\-hex\fR,
\fI\-\-maxlen=LEN\fR, \fI\-\-num=NUM\fR, \fI\-\-report=OPT\fR and
\fI\-\-start=LBA\fR options, if given, and ignores other options. It is only
implemented for the Report zones command currently. The algorithm may call
the Report zones command repeatedly, with the PARTIAL bit set and the Zone
start LBA field being increased as it goes. This continues until either
there is a match on the \fIZT\fR condition, \fI\-\-num=NUM\fR is exhausted
or the number of zones is exhausted.
.br
The \fIZT\fR numbers and abbreviations are listed when the \fI\-\-help\fR
option is given twice. Warning: using '!' for inverting the condition may
not be so practical as the shell (e.g. bash) may interpret '!' as having
special meaning. Placing single quotes around \fIZT\fR fixes the problem
for the bash shell (e.g. \-\-find='!c' meaning find the first zone whose
type is not conventional).
.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. When given twice, additional usage
information is output.
.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
When this option is used twice, it can be useful with either the
\fI\-\-brief\fR or \fI\-\-find=ZT\fR option to only output the header
and zone descriptor in hex that those two options would otherwise print
in ASCII in the absence of the \fI\-\-hex\fR option.
.br
The output format when this option is given thrice is suitable 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\-j\fR, \fB\-\-json[\fR=\fIJO\fR]
output is in JSON format instead of human readable form. See sg3_utils_json
manpage or use '?' for \fIJO\fR for a summary.
.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 16384 is used. The maximum allowed value of \fILEN\fR is 2097152.
.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. Without the PARTIAL bit set a ZBC disk
will attempt to form a response with all zones from \fILBA\fR to the end
of the disk. If there are a large number of zones (e.g. > 10,000) this
large response will be truncated so that it doesn't exceed the "allocation
length" field in the cdb (see \fI\-\-maxlen=LEN\fR). The advantage of doing
this is that the number of (remaining) zones on the disk can be calculated.
The disadvantage is the amount of time that may take.
.br
With the PARTIAL bit set in the cdb, only the number of zones implied by
the "allocation length" field are fetched. This may be considerably faster
than the same command without the PARTIAL bit set.
.br
When iterating through the zones on a ZBC disk, the process will be faster
when the PARTIAL bit is set. Typically \fI\-\-start=LBA\fR is set to zero
or the [LBA + zone_length] of the last zone reported in the previous
iteration.
.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, 0x3e for list zones apart from GAP zones, 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\-S\fR, \fB\-\-statistics\fR
reviews all or a limited number of report zones, collects statistics and
prints them (on stdout). The number of zones reviewed may be limited by
any combination of \fI\-\-num=NUM\fR, \fI\-\-report=OPT\fR and
\fI\-\-start=LBA\fR options. The long option name may be abbreviated to
\fI\-\-stats\fR.
.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 BSD\-2\-Clause 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_json(sg3_utils),
.B zbd(libzbd), blkzone(util-linux)