sg_rep_zones - Man Page

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

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.

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.

The exit status of sg_rep_zones is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

Written by Douglas Gilbert.

Report bugs to <dgilbert at interlog dot com>.

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.

sg_reset_wp,sg_zone,sg3_utils_json(sg3_utils), zbd(libzbd), blkzone(util-linux)

blkzone(8).