215 lines
10 KiB
Groff
215 lines
10 KiB
Groff
.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)
|