diff options
Diffstat (limited to 'doc/sg_requests.8')
-rw-r--r-- | doc/sg_requests.8 | 138 |
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) |