File: sg_start.8

package info (click to toggle)
sg3-utils 1.44-1
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 7,056 kB
  • sloc: ansic: 93,218; sh: 7,607; cpp: 2,947; makefile: 447
file content (273 lines) | stat: -rw-r--r-- 12,421 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
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
.TH SG_START "8" "October 2017" "sg3_utils\-1.43" SG3_UTILS
.SH NAME
sg_start \- send SCSI START STOP UNIT command: start, stop, load or eject
medium
.SH SYNOPSIS
.B sg_start
[\fI0\fR] [\fI1\fR] [\fI\-\-eject\fR] [\fI\-\-help\fR] [\fI\-\-fl=FL\fR]
[\fI\-\-immed\fR] [\fI\-\-load\fR] [\fI\-\-loej\fR] [\fI\-\-mod=PC_MOD\fR]
[\fI\-\-noflush\fR] [\fI\-\-pc=PC\fR] [\fI\-\-readonly\fR] [\fI\-\-start\fR]
[\fI\-\-stop\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
.PP
.B sg_start
[\fI\-\-eject\fR] [\fI\-\-fl=FL\fR] [\fI\-i\fR] [\fI\-\-imm=0|1\fR]
[\fI\-\-load\fR] [\fI\-\-loej\fR] [\fI\-\-mod=PC_MOD\fR] [\fI\-\-noflush\fR]
[\fI\-\-pc=PC\fR] [\fI\-r\fR] [\fI\-\-start\fR] [\fI\-\-stop\fR] [\fI\-v\fR]
[\fI\-V\fR] [\fI0|1\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
sg_start sends a SCSI START STOP UNIT command to the \fIDEVICE\fR with
the selected options. The most used options are \fI\-\-stop\fR to spin
down a disk and \fI\-\-start\fR to spin up a disk. Using \fI\-\-start\fR
on a disk that is already spinning is harmless. There is also finer grain
control with "power condition": active, idle or standby. This is set
with the \fI\-\-pc=PC\fR option. In some contexts the "stop" state can
be considered an additional power condition.
.PP
Devices that contain removable media such as cd/dvds can use the
\fI\-\-loej\fR option to load the medium when used in conjunction
with \fI\-\-start\fR (i.e. load medium then spin up). Alternatively
\fI\-\-loej\fR may be used to eject the medium when used in conjunction
with \fI\-\-stop\fR (i.e. spin down then eject medium). More simply, the
loading or ejecting of a removable medium can be requested with the
\fI\-\-load\fR or \fI\-\-eject\fR' option.
.PP
If no option or argument is given then a \fI\-\-start\fR is assumed; as the
utility's name suggests.
.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
\fB0\fR
same action as \fI\-\-stop\fR.
.TP
\fB1\fR
same action as \fI\-\-start\fR.
.TP
\fB\-e\fR, \fB\-\-eject\fR
stop the medium and eject it from the drive. Only appropriate for a
device with removable medium. Might be ignored (prevented), see below.
.TP
\fB\-h\fR, \fB\-\-help\fR
print out the usage message then exit.
.TP
\fB\-f\fR, \fB\-\-fl\fR=\fIFL\fR
sets the format layer number for the disc to "jump" to (defined in MMC\-5).
Values of \fIFL\fR can be 0 to 3. When this option is chosen, the FL, LoEj
and Start bits are set in the cdb as required by MMC\-5; thus the user does
not need to set the \fI\-\-start\fR and/or \fI\-\-load\fR options.
.TP
\fB\-i\fR, \fB\-\-immed\fR
sets the IMM bit on the START STOP UNIT command so this utility will
return immediately and not wait for the media to complete the requested
action. The default is to wait until the media to complete the requested
action before returning.
.TP
\fB\-l\fR, \fB\-\-load\fR
load the medium in the drive and start it. Only appropriate for a removable
medium.
.TP
\fB\-L\fR, \fB\-\-loej\fR
sets the LOEJ bit on the START STOP UNIT command. This loads the media when
the unit is started or eject it when the unit is stopped (i.e.  works in
conjunction with START bit in cdb). This option is ignored if 'pc > 0'.
Default is off (i.e. don't attempt to load or eject media). If a start/start
indication is not given (i.e. neither \fI\-\-start\fR nor \fI\-\-stop\fR)
and this option is given then a load and start action is assumed.
.TP
\fB\-m\fR, \fB\-\-mod\fR=\fIPC_MOD\fR
where \fIPC_MOD\fR is the 'power condition modifier' value. 0 to 15 (inclusive)
are valid and 0 is the default. This  'power condition modifier' field in the
cdb was added after sbc3r13.
.TP
\fB\-n\fR, \fB\-\-noflush\fR
do not perform a flush to media (e.g. like SYNCHRONIZE CACHE does) before
a variant of this utility that limits access to the media. Using the
\fB\-\-stop\fR option is an example of something that limits access to the
media. This 'noflush' field in the cdb was added after sbc3r13.
.TP
\fB\-O\fR, \fB\-\-old\fR
Switch to older style options. Please use as first option.
.TP
\fB\-p\fR, \fB\-\-pc\fR=\fIPC\fR
where \fIPC\fR is the 'power conditions' value. 0 to 15 (inclusive) are valid.
Default value is 0. When '\-\-pc=0' then \fB\-\-eject\fR, \fB\-\-load\fR,
\fB\-\-loej\fR, \fB\-\-start\fR and \fB\-\-stop\fR are active. Some common
values are 1 for the "active" power condition (SBC); 2 for the idle power
condition; 3 for the standby power condition; 5 for sleep power
condition (MMC); 7 for LU_CONTROL (SBC), 0xa (decimal 10) for
FORCE_IDLE_0 (SBC) and 0xb (decimal 11) for FORCE_STANDBY_0 (SBC). See recent
SBC\-3, MMC\-5 and SAS drafts at www.t10.org for more information.
.TP
\fB\-r\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR in read\-only mode. Maybe required in Linux to stop a
nuisance spin\-up if the \fIDEVICE\fR is an ATA disk. The nuisance spin\-up
may occur at the end of this command negating the effect of the
\fI\-\-stop\fR option.
.TP
\fB\-s\fR, \fB\-\-start\fR
start (spin\-up) the \fIDEVICE\fR. This sets the START bit in the cdb. Using
this option on an already started device is harmless. In the absence of
other options, this option defaults (i.e. set the START cdb bit).
.TP
\fB\-S\fR, \fB\-\-stop\fR
stop (spin\-down) the \fIDEVICE\fR. This clears the START bit in the cdb.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity. Can be used multiple times.
.TP
\fB\-V\fR, \fB\-\-version\fR
print out version string then exit.
.SH NOTES
To avoid confusion, only one of \fI0\fR, \fI1\fR \fI\-\-eject\fR,
\fI\-\-load\fR, \fI\-\-start\fR and \fI\-\-stop\fR should be given.
.PP
There is an associated "power condition" mode page (0x1a) in which timer
values can be set for transitioning to either idle or standby state after
a period of inactivity. The sdparm utility can be used to view the power
condition mode page and if required change it. If a \fIDEVICE\fR is in either
idle or standby power condition state then a REQUEST SENSE command (see
the sg_requests utility) should yield a sense key of "no sense" and an
additional sense code of "Low power condition on" on recent SCSI devices.
.PP
Ejection of removable media (e.g. 'sg_start \-\-eject /dev/hdd' where
the \fIDEVICE\fR is an ATAPI cd/dvd drive) may be prevented by a prior
SCSI PREVENT ALLOW MEDIUM REMOVAL command (see sg_prevent). In this
case this utility should fail with an error generated by the device:
illegal request / medium removal prevented. This can be overridden
using sg_prevent or, for example, 'sdparm \-\-command=unlock /dev/hdd'.
.PP
The SCSI TEST UNIT READY command can be used to find out whether a
\fIDEVICE\fR is ready to transfer data. If rotating media is stopped or
still coming up to speed, then the TEST UNIT READY command will yield
a "not ready" sense key and an more informative additional sense
code. See the sg_turs utility.
.PP
In the 2.4 series of Linux kernels the \fIDEVICE\fR must be a SCSI
generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks
and DVD drives) can also be specified. For example "sg_start 0 /dev/sda"
will work in the 2.6 series kernels.
.PP
In the Linux 2.6 series, especially with ATA disks, using this utility
to stop (spin down) a disk may not be sufficient and other mechanisms
will start the disk again some time later. The user might additionally
mark the disk as "offline" with 'echo offline > /sys/block/sda/device/state'
where sda is the block name of the disk. To restart the disk "offline"
can be replaced with "running". Note that once the 'state' is set to
offline, no SCSI commands can be sent to the device until it is set back
to running. Also stopping a disk via a pass\-through
interface (e.g. /dev/sg1 or /dev/bsg/1:0:0:0) may reduce unwanted side
effects (such as restarting it again when this utility completes).
.SH EXIT STATUS
The exit status of sg_start is 0 when it is successful. Otherwise 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.
.PP
Note that the action of \fI\-\-loej\fR is slightly different in the older
interface: when neither \fI\-\-start\fR nor \fI\-\-stop\fR (nor proxies
for them) are given, \fI\-\-loej\fR performs an eject operation. In the
same situation the newer interface will perform a load operation.
.PP
Earlier versions of sg_start had a '\-s' option to perform a SYNCHRONIZE
CACHE command before the START STOP UNIT command was issued. According to
recent SBC\-2 drafts this is done implicitly if required. Hence the '\-s'
option has been dropped.
.PP
All options, other than '\-v' and '\-V', can be given with a single "\-".
For example: "sg_start \-stop /dev/sda" and "sg_start \-\-stop /dev/sda"
are equivalent. The single "\-" form is for backward compatibility.
.TP
\fB0\fR
stop (spin\-down) \fIDEVICE\fR.
.TP
\fB1\fR
start (spin\-up) \fIDEVICE\fR.
.TP
\fB\-\-eject\fR
stop the medium and eject it from the drive.
.TP
\fB\-\-fl\fR=\fIFL\fR
sets the format layer number for the disc to "jump" to (defined in MMC\-5).
.TP
\fB\-i\fR
sets the IMM bit on the START STOP UNIT command so this utility will return
immediately and not wait for the media to spin down. Same effect
as '\-\-imm=1'. The default action (without this option or a '\-\-imm=1'
option) is to wait until the media spins down before returning.
.TP
\fB\-\-imm\fR=\fI0|1\fR
when the immediate bit is 1 then this utility returns immediately after the
\fIDEVICE\fR has received the command. When this option is 0 (the default)
then the utility returns once the command has completed its action (i.e. it
waits until the device is started or stopped).
.TP
\fB\-\-load\fR
load the medium in the drive and start it.
.TP
\fB\-\-loej\fR
sets the LOEJ bit in the START STOP UNIT cdb. When a "start" operation is
indicated, then a load and start is performed. When a "stop" operation is
indicated, then a stop and eject is performed. When neither a "start"
or "stop" operation is indicated does a stop and eject. [Note that the last
action differs from the new interface in which the option of this name
defaults to load and start.]
.TP
\fB-N\fR, \fB\-\-new\fR
Switch to the newer style options.
.TP
\fB\-\-mod\fR=\fIPC_MOD\fR
where \fIPC_MOD\fR is the 'power condition modifier' value. 0 to 15 (inclusive)
are valid and 0 is the default. This field was added after sbc3r13.
.TP
\fB\-\-noflush\fR
do not perform a flush to media (e.g. like SYNCHRONIZE CACHE does) before
a variant of this utility that limits access to the media. Using the
\fB\-\-stop\fR option is an example of something that limits access to the
media. This field was added after sbc3r13.
.TP
\fB\-\-pc\fR=\fIPC\fR
where \fIPC\fR is the 'power condition' value (in hex). 0 to f (inclusive)
are valid. Default value is 0.
.TP
\fB\-r\fR
see the \fI\-\-readonly\fR option above. May be useful for ATA disks.
.TP
\fB\-\-start\fR
start (spin\-up) \fIDEVICE\fR.
.TP
\fB\-\-stop\fR
stop (spin\-down) \fIDEVICE\fR. Same meaning as "0" argument.
.TP
\fB\-v\fR
verbose: outputs SCSI command in hex to console before with executing
it. '\-vv' and '\-vvv' are also accepted yielding greater 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 AUTHOR
Written by K. Garloff and D. Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2002\-2017 Kurt Garloff, 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_prevent(sg3_utils), sg_requests(sg3_utils), sg_turs(sg3_utils)
.B sdparm(sdparm)