File: sg_turs.8

package info (click to toggle)
sg3-utils 1.44-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, sid
  • size: 7,056 kB
  • sloc: ansic: 93,218; sh: 7,607; cpp: 2,947; makefile: 447
file content (136 lines) | stat: -rw-r--r-- 5,991 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
.TH SG_TURS "8" "March 2018" "sg3_utils\-1.43" SG3_UTILS
.SH NAME
sg_turs \- send one or more SCSI TEST UNIT READY commands
.SH SYNOPSIS
.B sg_turs
[\fI\-\-help\fR] [\fI\-\-low\fR] [\fI\-\-number=NUM\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-progress\fR] [\fI\-\-time\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
\fIDEVICE\fR
.PP
.B sg_turs
[\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\-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\-\-number\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\-\-num\fR=\fINUM\fR
same as \fI\-\-number=NUM\fR. Added for compatibility with sg_requests
which has taken over the role of polling the progress indication.
.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\-\-number=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\-\-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 utilty).
.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 commands). For this
utility the other exit status of interest is 2 corresponding to
the "not ready" sense key. 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\-n\fR=\fINUM\fR
performs TEST UNIT READY \fINUM\fR times. If not given defaults to 1.
Equivalent to \fI\-\-number=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\-2018 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)