doc/sg_z_act_query.8 - platform/external/sg3_utils - Git at Google

 .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)
	.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)