http://man-wiki.net/index.php/8:sg3_utils
sg3_utils - a package of utilities for sending SCSI commands
sg_* [--help] [--verbose] [--version] <scsi_device>
DESCRIPTION
sg3_utils is a package of utilities that send SCSI commands to the given <scsi_device> via a SCSI pass through
interface provided by the host operating system.
The names of all utilities start with "sg" and most start with "sg_" often followed by the abbreviation of the
name of the SCSI command that they send. For example the "sg_verify" utility sends the SCSI VERIFY command. A
mapping between SCSI commands and the sg3_utils utilities that issue them is given in the COVERAGE file.
SCSI draft standards can be found at http://www.t10.org . The standards themselves can be purchased from ANSI and
other standards organistions. A good overview of various SCSI standards can be seen at
http://www.t10.org/scsi-3.htm with the SCSI command sets in the upper part of the diagram. SCSI commands in com-
mon with all device types can be found in SPC of which SPC-4 is the latest major version. Block device specific
commands (e.g. as used by disks) can be in SBC, those for tape drives in SSC and those for CD/DVD drives in MMC.
There are two generations of command line option usage. The older utilities such as sg_inq have individual com-
mand line processing code (often found at the top of the main() function) based on a single "-" followed by one
or more characters. If an argument is needed then it follows a "=" (e.g. '-p=1f' in sg_modes). Various options
can be elided as long as it is not ambiguous (e.g. '-vv' to increase the verbosity). The <scsi_device> is any
device that can receive SCSI commands and is shown after the options in the synopsis. It may appear between other
options.
The second generation of newer utilties uses the getopt_long() function to parse command line options. With that
function, each option has two representations: a short form (e.g. '-v') and a longer form (e.g. '--verbose'). If
an argument is required then it follows a space in the short form and a "=" in the longer form (e.g. in the
sg_verify utility '-l 2a6h' and '--lba=2a6h' are equivalent). Again the <scsi_device> argument may appear between
or prior to other options.
Several sg3_utils utilities are based on the Unix dd command (e.g. sg_dd) and share its rather quirky command
line interface.
EXIT STATUS
To aid scripts that call these utilities, the exit status is set to indicate success(0) or failure (1 or more).
Note that some of the lower values correspond to the SCSI sense key values to which they correspond. The exit
status values are:
0 success
1 syntax error. Either illegal coomand line options, options with bad arguments or a combination of options
that is not permitted.
2 the <scsi_device> reports that it is not ready for the operation requested. The device may be in the pro-
cess of becoming ready (e.g. spinning up but not at speed) so the utility may work after a wait.
3 the <scsi_device> reports a medium or hardware error (or a blank check). For example an attempt to read a
corrupted block on a disk will yield this value.
5 the <scsi_device> reports an "illegal request" with an additional sense code other than "invalid operation
code". This is often a supported command with a field set requesting an unsupported capability. For com-
mands that require a "service action" field this value can indicate that the command is not supported.
6 the <scsi_device> reports a "unit attention" condition. This usually indicates that something unrelated to
the requested command has occurred (e.g. a device reset) potentially before the current SCSI command was
sent. The requested command has not been executed by the device. Note that unit attention conditions are
usually only reported once by a device.
9 the <scsi_device> reports an illegal request with an additional sense code of "invalid operation code"
which means that it doesn't support the requested command.
10 the <scsi_device> reports it has a check condition but "no sense" and non-zero information in its addi-
tional sense codes. Some polling commands (e.g. REQUEST SENSE) can receive this response.
11 the <scsi_device> reports a "recovered error". The requested command was successful. Most likely a utility
will report a recovered error to stderr and continue, probably leaving the utility with an exit status of
0 .
15 the utility is unable to open, close or use the given <scsi_device>. The given file name could be incor-
rect or there may be permission problems. Adding the '-v' option may give more information.
33 the command sent to <scsi_device> has timed out.
97 the response to a SCSI command failed sanity checks.
98 the <scsi_device> reports it has a check condition but the error doesn't fit into any of the above cate-
gories.
99 any errors that can't be categorized into values 1 to 98 may yield this value. This includes transport and
operating system errors after the command has been sent to the device.
Most of the error conditions reported above will be repeatable (an example of one that is not is "unit atten-
tion") so the utility can be run again with the '-v' option (or several) to obtain more information.
COMMON OPTIONS
--help | -h | -?
output the usage message then exit. In a few older utilities the '-h' option request hexadecimal output.
In these cases the '-?' option will output the usage message then exit.
--verbose | -v
increase the level of verbosity, (i.e. debug output). Such extra output is usually sent to stderr.
--version | -V
print the version string and then exit. Each utility has its own version number and date of last code
change.
Notice that the '--verbose' option can be used multiple times for more verbose output. Obviously the short form
('-vv') is more convenient than the longer form ('--verbose --verbose').
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright ? 1999-2006 Douglas Gilbert
Some utilities are distributed under a GPL version 2 license while others, usually more recent ones, are under a
FreeBSD license. The files that are common to almost all utilities and thus have the most reusable code, namely
sg_lib.[hc] and sg_cmds.[hc] are under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.
RELATED
sdparm(sdparm)
