1SG_TURS(8)                         SG3_UTILS                        SG_TURS(8)
2
3
4

NAME

6       sg_turs - send one or more SCSI TEST UNIT READY commands
7

SYNOPSIS

9       sg_turs   [--help]   [--low]  [--num=NUM]  [--number=NUM]  [--progress]
10       [--time] [--verbose] [--version] DEVICE
11
12       sg_turs [-n=NUM] [-p]  [-t] [-v] [-V] DEVICE
13

DESCRIPTION

15       This utility sends one or more SCSI TEST UNIT  READY  commands  to  the
16       DEVICE.  This  may be useful for timing the per command overhead.  Note
17       that TEST UNIT READY has no associated data,  just  a  6  byte  command
18       (with each byte a zero) and a returned SCSI status value.
19
20       This  utility  supports two command line syntaxes, the preferred one is
21       shown first in the synopsis and explained in this section. A later sec‐
22       tion  on  the  old  command  line  syntax  outlines the second group of
23       options.
24

OPTIONS

26       Arguments to long options are mandatory for short options as well.
27
28       -h, --help
29              print out the usage message then exit.
30
31       -l, --low
32              when [--progress] is not being used, this utility tries to  com‐
33              plete  the  SCSI TEST UNIT READY command(s) as quickly as possi‐
34              ble. Usually  it  calls  a  library  function  to  do  each  TUR
35              (sg_ll_test_unit_ready).  With  this  option  it  uses the lower
36              level sg_pt interface (see sg_pt.h) to save  a  little  time  on
37              each TUR.
38
39       -n, --num=NUM
40              performs  TEST UNIT READY NUM times. If not given defaults to 1.
41              These suffix multipliers are permitted: c C *1;  w  W  *2;  b  B
42              *512;  k  K  KiB  *1,024;  KB  *1,000;  m  M  MiB *1,048,576; MB
43              *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also
44              a  suffix  of  the  form "x<n>" multiplies the leading number by
45              <n>. Alternatively a hex number may be given, prefixed by either
46              '0x' or has a trailing 'h'.
47
48       --number=NUM
49              same  as --num=NUM. Added for compatibility with sg_requests and
50              other utilities in this  package.  The  sg_request  utility  has
51              taken over the role of polling the progress indication which was
52              originally assigned to the TEST UNIT READY command.  This  is  a
53              change by T10.
54
55       -O, --old
56              Switch to older style options. Please use as first option.
57
58       -p, --progress
59              show   progress  indication  (a  percentage)  if  available.  If
60              --num=NUM is given,  NUM  is  greater  than  1  and  an  initial
61              progress indication was detected then this utility waits 30 sec‐
62              onds before subsequent checks.  Exits when  NUM  is  reached  or
63              there  are no more progress indications.  Ignores --time option.
64              See NOTES section below.
65
66       -t, --time
67              after completing the requested number of TEST  UNIT  READY  com‐
68              mands, outputs the total duration and the average number of com‐
69              mands executed per second.
70
71       -v, --verbose
72              increase level or verbosity.
73
74       -V, --version
75              print version string then exit.
76

NOTES

78       The progress indication is optionally part of the sense  data.  When  a
79       prior  command  that  takes a long time to complete (and typically pre‐
80       cludes other media access commands) is  still  underway,  the  progress
81       indication  can be used to determine how long before the device returns
82       to its normal state. Around SPC-3 T10 changed the preferred command for
83       polling  the  progress indication from TEST UNIT READY to REQUEST SENSE
84       (see the sg_requests utilty).
85
86       The SCSI FORMAT command for disks used with the IMMED  bit  set  is  an
87       example  of  an  operation  that takes a significant amount of time and
88       precludes other media access  during  that  time.  The  IMMED  bit  set
89       instructs  the  FORMAT  command  to  return  control to the application
90       client once the format has commenced (see SBC-3). Several long duration
91       SCSI commands associated with tape drives also use the progress indica‐
92       tion (see SSC-3).
93
94       The DEVICE is opened with a read-only  flag  (e.g.  in  Unix  with  the
95       O_RDONLY flag).
96
97       Early standards suggested that the SCSI TEST UNIT READY command be used
98       for polling the progress indication. More recent standards seem to sug‐
99       gest the SCSI REQUEST SENSE command should be used instead.
100

EXIT STATUS

102       The exit status of sg_turs is 0 when it is successful (e.g. in the case
103       of a mechanical disk, it is spun up and ready to accept commands).  For
104       this  utility  the  other exit status of interest is 2 corresponding to
105       the "not ready" sense  key.  For  other  exit  status  values  see  the
106       sg3_utils(8) man page.
107

OLDER COMMAND LINE OPTIONS

109       The  options  in  this  section  were  the only ones available prior to
110       sg3_utils version 1.23 . Since then this utility defaults to the  newer
111       command  line options which can be overridden by using --old (or -O) as
112       the first option. See the ENVIRONMENT VARIABLES section for another way
113       to force the use of these older command line options.
114
115       -n=NUM performs  TEST UNIT READY NUM times. If not given defaults to 1.
116              Equivalent to --num=NUM in the main description.
117
118       -N, --new
119              Switch to the newer style options.
120
121       -p     show progress indication (a percentage) if  available.   Equiva‐
122              lent to --progress in the main description.
123
124       -t     after  completing  the  requested number of TEST UNIT READY com‐
125              mands, outputs the total duration and the average number of com‐
126              mands  executed  per  second.   Equivalent to --time in the main
127              description.
128
129       -v     increase level of verbosity.
130
131       -V     print out version string then exit.
132

ENVIRONMENT VARIABLES

134       Since    sg3_utils    version    1.23    the    environment    variable
135       SG3_UTILS_OLD_OPTS  can  be given. When it is present this utility will
136       expect the older command line options. So the presence of this environ‐
137       ment variable is equivalent to using --old (or -O) as the first command
138       line option.
139

AUTHORS

141       Written by D. Gilbert
142
144       Copyright © 2000-2019 Douglas Gilbert
145       This software is distributed under the GPL version 2. There is NO  war‐
146       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
147       POSE.
148

SEE ALSO

150       sg_inq, sg_requests (sg3_utils)
151
152
153
154sg3_utils-1.45                  September 2019                      SG_TURS(8)
Impressum