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

 .TH SG_REQUESTS "8" "October 2021" "sg3_utils\-1.47" SG3_UTILS
 .SH NAME
 sg_requests \- send one or more SCSI REQUEST SENSE commands
 .SH SYNOPSIS
 .B sg_requests
 [\fI\-\-desc\fR] [\fI\-\-error\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
 [\fI\-\-maxlen=LEN\fR] [\fI\-\-num=NUM\fR] [\fI\-\-number=NUM\fR]
 [\fI\-\-progress\fR] [\fI\-\-raw\fR] [\fI\-\-status\fR] [\fI\-\-time\fR]
 [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
 .SH DESCRIPTION
 .\" Add any additional description here
 .PP
 Send SCSI REQUEST SENSE command to \fIDEVICE\fR and output the parameter
 data response which is expected to be in sense data format. Both fixed
 and descriptor sense data formats are supported.
 .PP
 Multiple REQUEST SENSE commands can be sent with the \fI\-\-num=NUM\fR
 option. This can be used for timing purposes or monitoring the progress
 indication.
 .SH OPTIONS
 Arguments to long options are mandatory for short options as well.
 .TP
 \fB\-d\fR, \fB\-\-desc\fR
 sets the DESC bit in the REQUEST SENSE SCSI cdb. The \fIDEVICE\fR
 should return sense data in descriptor (rather than fixed) format. This
 will only occur if the \fIDEVICE\fR recognizes descriptor format (SPC\-3
 and later). If the device is pre SPC\-3 then setting a bit in a reserved
 field may cause a check condition status with an illegal request sense key,
 but will most likely be ignored.
 .TP
 \fB\-e\fR, \fB\-\-error\fR
 when used once it changes the REQUEST SENSE opcode from 0x3 to 0xff which
 should be rejected by the \fIDEVICE\fR. There is a small chance that the
 device vendor has implemented a vendor specific command at that opcode (0xff).
 When used twice the pass\-through call to send the SCSI command is bypassed.
 The idea here is to measure the user space overhead of this package's
 library to set up and process the response of a SCSI command. This option
 will be typically used with the \fI\-\-num=NUM\fR and \fI\-\-time\fR
 options where \fINUM\fR is a large number (e.g. 1000000).
 .TP
 \fB\-h\fR, \fB\-\-help\fR
 output the usage message then exit.
 .TP
 \fB\-H\fR, \fB\-\-hex\fR
 output response in ASCII hexadecimal.
 .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
 252 is used. The maximum value of \fILEN\fR is 255 (but SPC\-4 recommends 252).
 .TP
 \fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
 perform \fINUM\fR SCSI REQUEST SENSE commands, stopping when either \fINUM\fR
 is reached or an error occurs. The default value for \fINUM\fR is 1 .
 .TP
 \fB\-\-number\fR=\fINUM\fR
 same action as \fI\-\-num=NUM\fR. Added for compatibility with sg_turs.
 .TP
 \fB\-p\fR, \fB\-\-progress\fR
 show progress indication (a percentage) if available. If \fI\-\-num=NUM\fR
 is given, \fINUM\fR is greater than 1 and an initial progress indication
 was detected then this utility waits 30 seconds before subsequent checks.
 Exits when \fINUM\fR is reached or there are no more progress indications.
 Ignores \fI\-\-hex\fR, \fI\-\-raw\fR and \fI\-\-time\fR options. See
 NOTES section below.
 .TP
 \fB\-r\fR, \fB\-\-raw\fR
 output response in binary (to stdout).
 .TP
 \fB\-s\fR, \fB\-\-status\fR
 if the REQUEST SENSE command finished without error (as indicated by its
 SCSI status) then the contents of the parameter data are analysed as
 sense data and the exit status is set accordingly. The default
 action (i.e. when this option is not given) is to ignore the contents
 of the parameter data for the purposes of setting the exit status.
 Some types of error set a sense key of "NO SENSE" with non\-zero
 information in the additional sense code (e.g. the FAILURE PREDICTION
 THRESHOLD EXCEEDED group of codes); this results in an exit status
 value of 10. If the sense key is "NO SENSE" and both asc and ascq are
 zero then the exit status is set to 0 . See the sg3_utils(8) man page
 for exit status values.
 .TP
 \fB\-t\fR, \fB\-\-time\fR
 time the SCSI REQUEST SENSE command(s) and calculate the average number
 of operations per second.
 .TP
 \fB\-v\fR, \fB\-\-verbose\fR
 increase the level of verbosity, (i.e. debug output).
 Additionally the response (if received) is output in ASCII\-HEX. Use
 this option multiple times for greater verbosity.
 .TP
 \fB\-V\fR, \fB\-\-version\fR
 print the version string and then exit.
 .SH NOTES
 In SCSI 1 and 2 the REQUEST SENSE command was very important for error
 and warning processing in SCSI. The autosense capability rendered this
 command almost superfluous.
 .PP
 However recent SCSI drafts (e.g. SPC\-4 rev 14 and SBC\-3 rev 14) increase
 the utility of the REQUEST SENSE command. Idle and standby (low) power
 conditions can be detected with this command.
 .PP
 The REQUEST SENSE command is not marked as mandatory in SPC\-3 (i.e. for
 all SCSI devices) but is marked as mandatory in SBC\-2 (i.e. for disks),
 SSC\-3 (i.e. for tapes) and MMC\-4 (i.e. for CD/DVD/HD\-DVD/BD drives).
 .PP
 The progress indication is optionally part of the sense data. When a prior
 command that takes a long time to complete (and typically precludes other
 media access commands) is still underway, the progress indication can be used
 to determine how long before the device returns to its normal state.
 .PP
 The SCSI FORMAT command for disks used with the IMMED bit set is an example
 of an operation that takes a significant amount of time and precludes other
 media access during that time. The IMMED bit set instructs the FORMAT command
 to return control to the application client once the format has commenced (see
 SBC\-3). Several long duration SCSI commands associated with tape drives also
 use the progress indication (see SSC\-3).
 .PP
 Early standards suggested that the SCSI TEST UNIT READY command be used for
 polling the progress indication (see the sg_turs utility). Since SPC\-3 the
 standards suggest that the SCSI REQUEST SENSE command should be used instead.
 .PP
 The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the
 O_RDONLY flag).
 .SH EXIT STATUS
 The exit status of sg_requests 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 2004\-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_turs (sg3_utils)
	.TH SG_REQUESTS "8" "October 2021" "sg3_utils\-1.47" SG3_UTILS
	.SH NAME
	sg_requests \- send one or more SCSI REQUEST SENSE commands
	.SH SYNOPSIS
	.B sg_requests
	[\fI\-\-desc\fR] [\fI\-\-error\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
	[\fI\-\-maxlen=LEN\fR] [\fI\-\-num=NUM\fR] [\fI\-\-number=NUM\fR]
	[\fI\-\-progress\fR] [\fI\-\-raw\fR] [\fI\-\-status\fR] [\fI\-\-time\fR]
	[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
	.SH DESCRIPTION
	.\" Add any additional description here
	.PP
	Send SCSI REQUEST SENSE command to \fIDEVICE\fR and output the parameter
	data response which is expected to be in sense data format. Both fixed
	and descriptor sense data formats are supported.
	.PP
	Multiple REQUEST SENSE commands can be sent with the \fI\-\-num=NUM\fR
	option. This can be used for timing purposes or monitoring the progress
	indication.
	.SH OPTIONS
	Arguments to long options are mandatory for short options as well.
	.TP
	\fB\-d\fR, \fB\-\-desc\fR
	sets the DESC bit in the REQUEST SENSE SCSI cdb. The \fIDEVICE\fR
	should return sense data in descriptor (rather than fixed) format. This
	will only occur if the \fIDEVICE\fR recognizes descriptor format (SPC\-3
	and later). If the device is pre SPC\-3 then setting a bit in a reserved
	field may cause a check condition status with an illegal request sense key,
	but will most likely be ignored.
	.TP
	\fB\-e\fR, \fB\-\-error\fR
	when used once it changes the REQUEST SENSE opcode from 0x3 to 0xff which
	should be rejected by the \fIDEVICE\fR. There is a small chance that the
	device vendor has implemented a vendor specific command at that opcode (0xff).
	When used twice the pass\-through call to send the SCSI command is bypassed.
	The idea here is to measure the user space overhead of this package's
	library to set up and process the response of a SCSI command. This option
	will be typically used with the \fI\-\-num=NUM\fR and \fI\-\-time\fR
	options where \fINUM\fR is a large number (e.g. 1000000).
	.TP
	\fB\-h\fR, \fB\-\-help\fR
	output the usage message then exit.
	.TP
	\fB\-H\fR, \fB\-\-hex\fR
	output response in ASCII hexadecimal.
	.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
	252 is used. The maximum value of \fILEN\fR is 255 (but SPC\-4 recommends 252).
	.TP
	\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
	perform \fINUM\fR SCSI REQUEST SENSE commands, stopping when either \fINUM\fR
	is reached or an error occurs. The default value for \fINUM\fR is 1 .
	.TP
	\fB\-\-number\fR=\fINUM\fR
	same action as \fI\-\-num=NUM\fR. Added for compatibility with sg_turs.
	.TP
	\fB\-p\fR, \fB\-\-progress\fR
	show progress indication (a percentage) if available. If \fI\-\-num=NUM\fR
	is given, \fINUM\fR is greater than 1 and an initial progress indication
	was detected then this utility waits 30 seconds before subsequent checks.
	Exits when \fINUM\fR is reached or there are no more progress indications.
	Ignores \fI\-\-hex\fR, \fI\-\-raw\fR and \fI\-\-time\fR options. See
	NOTES section below.
	.TP
	\fB\-r\fR, \fB\-\-raw\fR
	output response in binary (to stdout).
	.TP
	\fB\-s\fR, \fB\-\-status\fR
	if the REQUEST SENSE command finished without error (as indicated by its
	SCSI status) then the contents of the parameter data are analysed as
	sense data and the exit status is set accordingly. The default
	action (i.e. when this option is not given) is to ignore the contents
	of the parameter data for the purposes of setting the exit status.
	Some types of error set a sense key of "NO SENSE" with non\-zero
	information in the additional sense code (e.g. the FAILURE PREDICTION
	THRESHOLD EXCEEDED group of codes); this results in an exit status
	value of 10. If the sense key is "NO SENSE" and both asc and ascq are
	zero then the exit status is set to 0 . See the sg3_utils(8) man page
	for exit status values.
	.TP
	\fB\-t\fR, \fB\-\-time\fR
	time the SCSI REQUEST SENSE command(s) and calculate the average number
	of operations per second.
	.TP
	\fB\-v\fR, \fB\-\-verbose\fR
	increase the level of verbosity, (i.e. debug output).
	Additionally the response (if received) is output in ASCII\-HEX. Use
	this option multiple times for greater verbosity.
	.TP
	\fB\-V\fR, \fB\-\-version\fR
	print the version string and then exit.
	.SH NOTES
	In SCSI 1 and 2 the REQUEST SENSE command was very important for error
	and warning processing in SCSI. The autosense capability rendered this
	command almost superfluous.
	.PP
	However recent SCSI drafts (e.g. SPC\-4 rev 14 and SBC\-3 rev 14) increase
	the utility of the REQUEST SENSE command. Idle and standby (low) power
	conditions can be detected with this command.
	.PP
	The REQUEST SENSE command is not marked as mandatory in SPC\-3 (i.e. for
	all SCSI devices) but is marked as mandatory in SBC\-2 (i.e. for disks),
	SSC\-3 (i.e. for tapes) and MMC\-4 (i.e. for CD/DVD/HD\-DVD/BD drives).
	.PP
	The progress indication is optionally part of the sense data. When a prior
	command that takes a long time to complete (and typically precludes other
	media access commands) is still underway, the progress indication can be used
	to determine how long before the device returns to its normal state.
	.PP
	The SCSI FORMAT command for disks used with the IMMED bit set is an example
	of an operation that takes a significant amount of time and precludes other
	media access during that time. The IMMED bit set instructs the FORMAT command
	to return control to the application client once the format has commenced (see
	SBC\-3). Several long duration SCSI commands associated with tape drives also
	use the progress indication (see SSC\-3).
	.PP
	Early standards suggested that the SCSI TEST UNIT READY command be used for
	polling the progress indication (see the sg_turs utility). Since SPC\-3 the
	standards suggest that the SCSI REQUEST SENSE command should be used instead.
	.PP
	The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the
	O_RDONLY flag).
	.SH EXIT STATUS
	The exit status of sg_requests 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 2004\-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_turs (sg3_utils)