diff options
Diffstat (limited to 'doc/sg_rep_zones.8')
| -rw-r--r-- | doc/sg_rep_zones.8 | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/doc/sg_rep_zones.8 b/doc/sg_rep_zones.8 new file mode 100644 index 00000000..49ee070a --- /dev/null +++ b/doc/sg_rep_zones.8 @@ -0,0 +1,214 @@ +.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) |