diff options
Diffstat (limited to 'doc/sg_z_act_query.8')
| -rw-r--r-- | doc/sg_z_act_query.8 | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/doc/sg_z_act_query.8 b/doc/sg_z_act_query.8 new file mode 100644 index 00000000..7cda1e2c --- /dev/null +++ b/doc/sg_z_act_query.8 @@ -0,0 +1,115 @@ +.TH SG_Z_ACT_QUERY "8" "December 2021" "sg3_utils\-1.48" SG3_UTILS +.SH NAME +sg_z_act_query \- send a SCSI ZONE ACTIVATE or ZONE QUERY command +.SH SYNOPSIS +.B sg_z_act_query +[\fI\-\-activate\fR] [\fI\-\-all\fR] [\fI\-\-force\fR] [\fI\-\-help\fR] +[\fI\-\-hex\fR] [\fI\-\-inhex=FN\fR] [\fI\-\-maxlen=LEN\fR] +[\fI\-\-num=ZS\fR] [\fI\-\-other=ZDID\fR] [\fI\-\-query\fR] [\fI\-\-raw\fR] +[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-zone=ID\fR] +\fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Sends a SCSI ZONE ACTIVATE or ZONE QUERY command to the \fIDEVICE\fR. If the +\fI\-\-activate\fR option is not given, then a ZONE QUERY command is sent. +These commands were added in the ZBC\-2 draft revision 4 (zbc2r04.pdf). +.PP +Both of these commands have similar cdb_s and responses hence they are both +placed in this utility. The difference is that only the ZONE ACTIVATE command +will potentially activate or deactivate zones. Both commands will perform +a "Verify activations operation" as defined in ZBC\-2 . +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-A\fR, \fB\-\-activate\fR +sends a ZONE ACTIVATE command to the \fIDEVICE\fR. The default (i.e. without +this option) is to send a ZONE QUERY command. +.TP +\fB\-a\fR, \fB\-\-all\fR +sets the ALL field in the cdb. +.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. +.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 activation 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 +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 +By default it is assumed the response is from a ZONE QUERY command but +that shouldn't matter because the response of the ZONE ACTIVATE and +ZONE QUERY commands is of the same form. +.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 8192 is used. The maximum allowed value of \fILEN\fR is 1048576. +.br +The draft standard disallows allocation lengths less than 64. +.TP +\fB\-n\fR, \fB\-\-num\fR=\fIZS\fR +where \fIZS\fR is placed in the "Number of zones" field in the cdb. This +option is usually ignored if the \fI\-\-all\fR option is given. If the +\fI\-\-all\fR option is not given, the default value of this field is 1 . +.TP +\fB\-o\fR, \fB\-\-other\fR=\fIZDID\fR +where the \fIZDID\fR value will be placed in the "Other zone domain ID" +field of the cdb to be sent to the \fIDEVICE\fR. +.TP +\fB\-q\fR, \fB\-\-query\fR +causes the ZONE QUERY command to be sent to the \fIDEVICE\fR. Since this +is the default action, this option is typically not needed. If both this +option and the \fI\-\-activate\fR option are given, an error will be +reported (and no command will be sent). +.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\-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\-z\fR, \fB\-\-zone\fR=\fIID\fR +where \fIID\fR is placed in the cdb's ZONE ID field. A zone id is a zone +start logical block address (LBA). The default value is 0. \fIID\fR is +assumed to be in decimal unless prefixed with '0x' or has a trailing 'h' +which indicate hexadecimal. The maximum value that can be given is +2^64 - 2. In the unlikely event of wanting to give 2^64 - 1, enter "\-1". +.SH EXIT STATUS +The exit status of sg_z_act_query 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 2021 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_zone,sg_rep_zones,sg_reset_wp(sg3_utils) |