diff options
Diffstat (limited to 'doc/sg_turs.8')
-rw-r--r-- | doc/sg_turs.8 | 152 |
1 files changed, 152 insertions, 0 deletions
diff --git a/doc/sg_turs.8 b/doc/sg_turs.8 new file mode 100644 index 00000000..bec99f59 --- /dev/null +++ b/doc/sg_turs.8 @@ -0,0 +1,152 @@ +.TH SG_TURS "8" "November 2022" "sg3_utils\-1.48" SG3_UTILS +.SH NAME +sg_turs \- send one or more SCSI TEST UNIT READY commands +.SH SYNOPSIS +.B sg_turs +[\fI\-\-delay=MS\fR] [\fI\-\-help\fR] [\fI\-\-low\fR] [\fI\-\-num=NUM\fR] +[\fI\-\-number=NUM\fR] [\fI\-\-progress\fR] [\fI\-\-time\fR] +[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR +.PP +.B sg_turs +[\fI\-d=MS\fR] [\fI\-n=NUM\fR] [\fI\-p\fR] [\fI\-t\fR] [\fI\-v\fR] [\fI\-V\fR] +\fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +This utility sends one or more SCSI TEST UNIT READY commands to the +\fIDEVICE\fR. This may be useful for timing the per command overhead. +Note that TEST UNIT READY has no associated data, just a 6 byte +command (with each byte a zero) and a returned SCSI status value. +.PP +This utility supports two command line syntaxes, the preferred one is +shown first in the synopsis and explained in this section. A later section +on the old command line syntax outlines the second group of options. +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR +this option causes a delay of \fIMS\fR milliseconds to occur before each +TEST UNIT READY command is issued. +.TP +\fB\-h\fR, \fB\-\-help\fR +print out the usage message then exit. +.TP +\fB\-l\fR, \fB\-\-low\fR +when [\fI\-\-progress\fR] is not being used, this utility tries to complete +the SCSI TEST UNIT READY command(s) as quickly as possible. Usually it +calls a library function to do each TUR (sg_ll_test_unit_ready). With this +option it uses the lower level sg_pt interface (see sg_pt.h) to save a +little time on each TUR. +.TP +\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR +performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1. +These suffix multipliers are permitted: c C *1; w W *2; b B *512; +k K KiB *1,024; KB *1,000; m M MiB *1,048,576; MB *1,000,000; +g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix of the +form "x<n>" multiplies the leading number by <n>. Alternatively a hex +number may be given, prefixed by either '0x' or has a trailing 'h'. +.TP +\fB\-\-number\fR=\fINUM\fR +same as \fI\-\-num=NUM\fR. Added for compatibility with sg_requests and +other utilities in this package. The sg_request utility has taken over the +role of polling the progress indication which was originally assigned to +the TEST UNIT READY command. This is a change by T10. +.TP +\fB\-O\fR, \fB\-\-old\fR +Switch to older style options. Please use as first option. +.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. +If the \fI\-\-delay=MS\fR option is given then it will wait for that number +of milliseconds instead of 30 seconds. +Exits when \fINUM\fR is reached or there are no more progress indications. +Ignores \fI\-\-time\fR option. See NOTES section below. +.TP +\fB\-t\fR, \fB\-\-time\fR +after completing the requested number of TEST UNIT READY commands, outputs +the total duration and the average number of commands executed per second. +.TP +\fB\-v\fR, \fB\-\-verbose\fR +increase level or verbosity. +.TP +\fB\-V\fR, \fB\-\-version\fR +print version string then exit. +.SH NOTES +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. Around +SPC\-3 T10 changed the preferred command for polling the progress indication +from TEST UNIT READY to REQUEST SENSE (see the sg_requests utility). +.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 +The \fIDEVICE\fR is opened with a read\-only flag (e.g. in Unix with the +O_RDONLY flag). +.PP +Early standards suggested that the SCSI TEST UNIT READY command be used for +polling the progress indication. More recent standards seem to suggest +the SCSI REQUEST SENSE command should be used instead. +.SH EXIT STATUS +The exit status of sg_turs is 0 when it is successful (e.g. in the case of +a mechanical disk, it is spun up and ready to accept IO commands). For this +utility the other exit status values of interest are 2, 12 and 13. 12 is for +the case when the sense key is "not ready" [0x2] and the additional sense +code ends with "Target port in standby state" [0x4, 0xb]. 13 is for the +case when the sense key is "not ready" [0x2] and the additional sense code +is "Target port in unavailable state" [0x4, 0xc]. All other cases when +the sense key is "not ready" [0x2] will set the exit status to 2. +For other exit status values see the sg3_utils(8) man page. +.SH OLDER COMMAND LINE OPTIONS +The options in this section were the only ones available prior to sg3_utils +version 1.23 . Since then this utility defaults to the newer command line +options which can be overridden by using \fI\-\-old\fR (or \fI\-O\fR) as the +first option. See the ENVIRONMENT VARIABLES section for another way to +force the use of these older command line options. +.TP +\fB\-d\fR, \fB\-\-delay\fR=\fIMS\fR +this option causes a delay of \fIMS\fR milliseconds to occur before each +TEST UNIT READY command is issued. +.TP +\fB\-n\fR=\fINUM\fR +performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1. +Equivalent to \fI\-\-num=NUM\fR in the main description. +.TP +\fB-N\fR, \fB\-\-new\fR +Switch to the newer style options. +.TP +\fB\-p\fR +show progress indication (a percentage) if available. +Equivalent to \fI\-\-progress\fR in the main description. +.TP +\fB\-t\fR +after completing the requested number of TEST UNIT READY commands, outputs +the total duration and the average number of commands executed per second. +Equivalent to \fI\-\-time\fR in the main description. +.TP +\fB\-v\fR +increase level of verbosity. +.TP +\fB\-V\fR +print out version string then exit. +.SH ENVIRONMENT VARIABLES +Since sg3_utils version 1.23 the environment variable SG3_UTILS_OLD_OPTS +can be given. When it is present this utility will expect the older command +line options. So the presence of this environment variable is equivalent to +using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option. +.SH AUTHORS +Written by D. Gilbert +.SH COPYRIGHT +Copyright \(co 2000\-2022 Douglas Gilbert +.br +This software is distributed under the GPL version 2. There is NO +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +.SH "SEE ALSO" +.B sg_inq, sg_requests (sg3_utils) |