doc/sg_z_act_query.8

.TH SG_Z_ACT_QUERY "8" "November 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 where 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 contents
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 FreeBSD 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)