153 lines
6.8 KiB
Groff
153 lines
6.8 KiB
Groff
.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)
|