diff options
Diffstat (limited to 'doc/sg_start.8')
| -rw-r--r-- | doc/sg_start.8 | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/doc/sg_start.8 b/doc/sg_start.8 new file mode 100644 index 00000000..1b251c1e --- /dev/null +++ b/doc/sg_start.8 @@ -0,0 +1,283 @@ +.TH SG_START "8" "April 2021" "sg3_utils\-1.47" 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. +.PP +Linux note: best not to use a standard block device name (e.g. /dev/sdc) +with the \fI\-\-stop\fR option. Use a sg or bsg device node instead (see +lsscsi(8) ). The block layer will sometimes notice the disk spinning +down and decide: "that's not right" and spin it up again! +.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. +Note, this is an operation that can be done on a tape drive or CD/DVD/BD +player, not on a hard disk or SSD! +.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. +This operation is typically done on a hard disk or SSD. In the case of a +SSD it will be placed in low power mode and may need a start operation +later before normal IO can resume. +.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\-2021 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), lsscsi(lsscsi) |