1 files changed, 138 insertions, 0 deletions
diff --git a/doc/sg_requests.8 b/doc/sg_requests.8
new file mode 100644
index 00000000..e1c1605d
--- /dev/null
+++ b/doc/sg_requests.8
@@ -0,0 +1,138 @@
+.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)