Provided by: sg3-utils_1.48-2ubuntu1_amd64 
NAME
sg_rep_zones - send SCSI REPORT ZONES, REALMS or ZONE DOMAINS command
SYNOPSIS
sg_rep_zones [--brief] [--domain] [--find=ZT] [--force] [--help] [--hex] [--inhex=FN] [--json[=JO]]
[--js-file=JFN] [--locator=LBA] [--maxlen=LEN] [--num=NUM] [--partial] [--raw] [--readonly] [--realm]
[--report=OPT] [--start=LBA] [--statistics] [--verbose] [--version] [--wp] DEVICE
DESCRIPTION
Sends a SCSI REPORT ZONES, REPORT REALMS or REPORT ZONE DOMAINS command to DEVICE 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.
The REPORT ZONE DOMAINS command will be sent (and decoded) when the --domain option is given. The REPORT
REALMS command will be sent (and decoded) when the --realm option is given.
Rather than send a SCSI command to DEVICE, if the --inhex=FN option is given, then the contents of the
file named FN are decoded as ASCII hex (or binary if --raw 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 --domain or
--realm option is given then the corresponding command response is assumed.
OPTIONS
Arguments to long options are mandatory for short options as well.
-b, --brief
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.
-d, --domain
send or decode the SCSI REPORT ZONE DOMAINS command.
-F, --find=ZT
where ZT is a zone type number or an abbreviation for a zone type. If ZT 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 not the given zone type.
The algorithm used by this option takes into account the --hex, --maxlen=LEN, --num=NUM,
--report=OPT and --start=LBA 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 ZT condition, --num=NUM is exhausted or the number
of zones is exhausted.
The ZT numbers and abbreviations are listed when the --help 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 ZT fixes the problem for the bash shell
(e.g. --find='!c' meaning find the first zone whose type is not conventional).
-f, --force
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.
-h, --help
output the usage message then exit. When given twice, additional usage information is output.
-H, --hex
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).
When this option is used twice, it can be useful with either the --brief or --find=ZT 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 --hex option.
The output format when this option is given thrice is suitable for a later invocation with the
--inhex=FN option.
-i, --inhex=FN
where FN is a file name whose contents are assumed to be ASCII hexadecimal. If DEVICE is also
given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file
named FN. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more
information. If the --raw option is also given then the contents of FN are treated as binary.
Note that by default this utility assumes then contents are the response from a REPORT ZONES
command. Use the --domain or --realm option for decoding the other two commands.
-j[=JO], --json[=JO]
output is in JSON format instead of plain text form. Note that arguments to the short and long
form are themselves optional and if present start with "=" and no whitespace is permitted around
that "=".
See sg3_utils_json manpage or use '?' for JO to get a summary.
-J, --js-file=JFN
output is in JSON format and it is sent to a file named JFN. If that file exists then it is
truncated. By default, the JSON output is sent to stdout.
When this option is given, the --json[=JO] option is implied and need not be given. The
--json[=JO] option may still be needed to set the JO parameter to non-default values.
-l, --locator=LBA
where LBA plays a similar role as it does in --start=LBA. It is the field name used in the REPORT
REALMS and REPORT ZONE DOMAINS commands.
-m, --maxlen=LEN
where LEN is the (maximum) response length in bytes. It is placed in the cdb's "allocation length"
field. If not given (or LEN is zero) then 16384 is used. The maximum allowed value of LEN is
2097152.
-n, --num=NUM
where NUM 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.
-p, --partial
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 LBA 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 --maxlen=LEN). 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.
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.
When iterating through the zones on a ZBC disk, the process will be faster when the PARTIAL bit is
set. Typically --start=LBA is set to zero or the [LBA + zone_length] of the last zone reported in
the previous iteration.
-r, --raw
output response in binary (to stdout) unless the --inhex=FN option is also given. In that case the
input file name (FN) is decoded as binary (and the output is _not_ in binary (but may be hex)).
-R, --readonly
open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it
read-write.
-e, --realm
send or decode the SCSI REPORT REALMS command.
-o, --report=OPT
where OPT 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 --help option is given
twice ( or the equivalent '-hh') a list of available reporting options (as of writing) for each
command is output.
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'.
-s, --start=LBA
where LBA is at the start or within the first zone to be reported. The default value is 0. If LBA
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.
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 --locator=LBA and --start=LBA are
interchangeable.
-S, --statistics
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 --num=NUM, --report=OPT and
--start=LBA options. The long option name may be abbreviated to --stats.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
-w, --wp
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 --num=NUM and --start=LBA
options.
EXIT STATUS
The exit status of sg_rep_zones is 0 when it is successful. Otherwise see the sg3_utils(8) man page.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2014-2023 Douglas Gilbert
This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO
sg_reset_wp,sg_zone,sg3_utils_json(sg3_utils), zbd(libzbd), blkzone(util-linux)
sg3_utils-1.48 June 2023 SG_REP_ZONES(8)