Provided by: sg3-utils_1.36-1ubuntu1_amd64 
NAME
sg3_utils - a package of utilities for sending SCSI commands
SYNOPSIS
sg_* [--help] [--hex] [--maxlen=LEN] [--raw] [--verbose] [--version] [OTHER_OPTIONS]
DEVICE
DESCRIPTION
sg3_utils is a package of utilities that send SCSI commands to the given 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
name, or a shortening 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 shown 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 organizations. A good overview of various SCSI
standards can be seen in http://www.t10.org/scsi-3.htm with the SCSI command sets in the
upper part of the diagram. SCSI commands in common 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) are in SBC, those for tape drives in SSC and those for CD/DVD/BD drives in
MMC.
It is becoming more common to control ATA disks with the SCSI command set. This involves
the translation of SCSI commands to their corresponding ATA equivalents (and that is an
imperfect mapping in some cases). The relevant standard is called SCSI to ATA Translation
(SAT and SAT-2 are now standards at INCITS(ANSI) and ISO while SAT-3 is at the draft
stage). The logic to perform the command translation is often called a SAT Layer or SATL
and may be within an operating system, in host bus adapter firmware or in an external
device (e.g. associated with a SAS expander). See http://www.t10.org for more information.
There is some support for SCSI tape devices but not for their basic commands. The reader
is referred to the "mt" utility.
There are two generations of command line option usage. The newer utilities (written since
July 2004) use 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 (optionally) in the
short form and a "=" in the longer form (e.g. in the sg_verify utility '-l 2a6h' and
'--lba=2a6h' are equivalent). Note that with getopt_long(), short form options can be
elided, for example: '-all' is equivalent to '-a -l -l'. The DEVICE argument may appear
after, between or prior to any options.
The older utilities, such as sg_inq, had individual command line processing code typically
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 with its older interface). Various options can be
elided as long as it is not ambiguous (e.g. '-vv' to increase the verbosity).
Over time the command line interface of these older utilities became messy and overloaded
with options. So in sg3_utils version 1.23 the command line interface of these older
utilities was altered to have both a cleaner getopt_long() interface and their older
interface for backward compatibility. By default these older utilities use their
getopt_long() based interface. That can be overridden by defining the SG3_UTILS_OLD_OPTS
environment variable or using '-O' or '--old' as the first command line option. The man
pages of the older utilities documents the details.
Several sg3_utils utilities are based on the Unix dd command (e.g. sg_dd) and permit
copying data at the level of SCSI READ and WRITE commands. sg_dd is tightly bound to Linux
and hence is not ported to other OSes. A more generic utility (than sg_dd) called ddpt in
a package of the same name has been ported to other OSes.
LINUX DEVICE NAMING
Normal disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc, etc. SCSI disks in
Linux have always had names like that but in recent Linux kernels (e.g. lk 2.6 series) it
is becoming more common for almost all disks to be named like that. Partitions within a
disk are specified by a number appended to the device name, starting at 1 (e.g. /dev/sda1
).
Tape drives are named /dev/st<num> or /dev/nst<num> where <num> starts at zero.
Additionally one letter from this list: "lma" may be appended to the name. CD, DVD and BD
readers (and writers) are named /dev/sr<num> where <num> start at zero. There are less
used SCSI device type names, the dmesg and the lsscsi commands may help to find if any are
attached to a running system.
There is also a SCSI device driver which offers alternate generic access to SCSI devices.
It uses names of the form /dev/sg<num> where <num> starts at zero. The "lsscsi -g" command
may be useful in finding these and which generic name corresponds to a device type name
(e.g. /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI generic
driver was introduced and its names are of the form /dev/bsg/<h:c:t:l> where h, c, t and l
are numbers. Again see the lsscsi command to find the correspondence between that SCSI
tuple (i.e. <h:c:t:l>) and alternate device names.
Prior to the Linux kernel 2.6 series these utilities could only use generic device names
(e.g. /dev/sg1 ). In almost all cases in the Linux kernel 2.6 series, any device name can
be used by these utilities.
WINDOWS DEVICE NAMING
Storage and related devices can have several device names in Windows. Probably the most
common in the volume name (e.g. "D:"). There are also a "class" device names such as
"PhysicalDrive<n>", "CDROM<n>" and "TAPE<n>". <n> is an integer starting at 0 allocated in
ascending order as devices are discovered (and sometimes rediscovered).
Some storage devices have a SCSI lower level device name which starts with a SCSI (pseudo)
adapter name of the form "SCSI<n>:". To this is added sub-addressing in the form of a
"bus" number, a "target" identifier and a LUN (Logical Unit Number). The "bus" number is
also known as a "PathId". These are assembled to form a device name of the form:
"SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted in which case a LUN
of zero is assumed. This lower level device name cannot often be used directly since
Windows blocks attempts to use it if a class driver has "claimed" the device. There are
SCSI device types (e.g. Automation/Drive interface type) for which there is no class
driver. At least two transports ("bus types" in Windows jargon): USB and IEEE 1394 do not
have a "scsi" device names of this form.
In keeping with DOS file system conventions, the various device names can be given in
upper, lower or mixed case. Since "PhysicalDrive<n>" is tedious to write, a shortened form
of "PD<n>" is permitted by all utilities in this package.
A single device (e.g. a disk) can have many device names. For example: "PD0" can also be
"C:", "D:" and "SCSI0:0,1,0". The two volume names reflect that the disk has two
partitions on it. Disk partitions that are not recognized by Windows are not usually given
a volume name. However Vista does show a volume name for a disk which has no partitions
recognized by it and when selected invites the user to format it (which may be rather
unfriendly to other OSes).
These utilities assume a given device name is in the Win32 device namespace. To make that
explicit "\\.\" can be prepended to the device names mentioned in this section. Beware
that backslash is an escape character in Unix like shells and the C programming language.
In a shell like Msys (from MinGW) each backslash may need to be typed twice.
The sg_scan utility within this package lists out Windows device names in a form that is
suitable for other utilities in this package to use.
FREEBSD DEVICE NAMING
SCSI disks have block names of the form /dev/da<num> where <num> is an integer starting at
zero. The "da" is replaced by "sa" for SCSI tape drives and "cd" for SCSI CD/DVD/BD
drives. Each SCSI device has a corresponding pass-through device name of the form
/dev/pass<num> where <num> is an integer starting at zero. The "camcontrol devlist"
command may be useful for finding out which SCSI device names are available and the
correspondence between between class and pass-through names.
SOLARIS DEVICE NAMING
SCSI device names below the /dev directory have a form like: c5t4d3s2 where the number
following "c" is the controller (HBA) number, the number following "t" is the target
number (from the SCSI parallel interface days) and the number following "d" is the LUN.
Following the "s" is the slice number which is related to a partition and by convention
"s2" is the whole disk.
OpenSolaris also has a c5t4d3p2 form where the number following the "p" is the partition
number apart from "p0" which is the whole disk. So a whole disk may be referred to as
either c5t4d3, c5t4d3s2 or c5t4d3p0 .
And these device names are duplicated in the /dev/dsk and /dev/rdsk directories. The
former is the block device name and the latter is for "raw" (or char device) access which
is what sg3_utils needs. So in OpenSolaris something of the form 'sg_inq
/dev/rdsk/c5t4d3p0' should work. If it doesn't work then add a '-vvv' option for more
debug information. Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk" changed to
"dsk") will result in an "inappropriate ioctl for device" error.
The device names within the /dev directory are typically symbolic links to much longer
topological names in the /device directory. In Solaris cd/dvd/bd drives seem to be treated
as disks and so are found in the /dev/rdsk directory. Tape drives appear in the /dev/rmt
directory.
There is also a sgen (SCSI generic) driver which by default does not attach to any device.
See the /kernel/drv/sgen.conf file to control what is attached. Any attached device will
have a device name of the form /dev/scsi/c5t4d3 .
Listing available SCSI devices in Solaris seems to be a challenge. "Use the 'format'
command" advice works but seems a very dangerous way to list devices. [It does prompt
again before doing any damage.] 'devfsadm -Cv' cleans out the clutter in the /dev/rdsk
directory, only leaving what is "live". The "cfgadm -v" command looks promising.
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. The exit status values are:
0 success
1 syntax error. Either illegal command line options, options with bad arguments or a
combination of options that is not permitted.
2 the DEVICE reports that it is not ready for the operation requested. The device may
be in the process of becoming ready (e.g. spinning up but not at speed) so the
utility may work after a wait.
3 the 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 DEVICE reports an "illegal request" with an additional sense code other than
"invalid command operation code". This is often a supported command with a field
set requesting an unsupported capability. For commands that require a "service
action" field this value can indicate that the command with that service action
value is not supported.
6 the 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 DEVICE reports an illegal request with an additional sense code of "invalid
command operation code" which means that it doesn't support the requested command.
11 the DEVICE reports an aborted command. In some cases aborted commands can be
retried immediately (e.g. if the transport aborted the command due to congestion).
15 the utility is unable to open, close or use the given DEVICE. The given file name
could be incorrect or there may be permission problems. Adding the '-v' option may
give more information.
20 the DEVICE reports it has a check condition but "no sense" and non-zero information
in its additional sense codes. Some polling commands (e.g. REQUEST SENSE) can
receive this response.
21 the 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 .
33 the command sent to DEVICE has timed out.
97 a SCSI command response failed sanity checks.
98 the DEVICE reports it has a check condition but the error doesn't fit into any of
the above categories.
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 attention") so the utility can be run again with the '-v' option (or several)
to obtain more information.
COMMON OPTIONS
Arguments to long options are mandatory for short options as well. In the short form an
argument to an option uses zero or more spaces as a separator (i.e. the short form does
not use "=" as a separator).
If an option takes a numeric argument then that argument is assumed to be decimal unless
otherwise indicated (e.g. with a leading "0x", a trailing "h" or as noted in the usage
message).
Some options are used uniformly in most of the utilities in this package. Those options
are listed below. Note that there are some exceptions.
-h, -?, --help
output the usage message then exit. In a few older utilities the '-h' option
requests hexadecimal output. In these cases the '-?' option will output the usage
message then exit.
-H, --hex
for SCSI commands that yield a non-trivial response, print out that response in
ASCII hexadecimal.
-m, --maxlen=LEN
several important SCSI commands (e.g. INQUIRY and MODE SENSE) have response lengths
that vary depending on many factors, only some of which these utilities take into
account. The maximum response length is typically specified in the 'allocation
length' field of the cdb. In the absence of this option, several utilities use a
default allocation length (sometimes recommended in the SCSI draft standards) or a
"double fetch" strategy. See sg_logs(8) for its description of a "double fetch"
strategy. These techniques are imperfect and in the presence of faulty SCSI targets
can cause problems (e.g. some USB mass storage devices freeze if they receive an
INQUIRY allocation length other than 36). Also use of this option disables any
"double fetch" strategy that may have otherwise been used.
-r, --raw
for SCSI commands that yield a non-trivial response, output that response in binary
to stdout. If any error messages or warning are produced they are usually sent to
stderr. Some utilities that consume data to send to the device along with the SCSI
command, use this option to provide that data or indicate that it can be read from
stdin.
-v, --verbose
increase the level of verbosity, (i.e. debug output). Can be used multiple times to
further increase verbosity. The additional output is usually sent to stderr.
-V, --version
print the version string and then exit. Each utility has its own version number and
date of last code change.
NUMERIC ARGUMENTS
Many utilities have command line options that take numeric arguments. These numeric
arguments can be large values (e.g. a logical block address (LBA) on a disk) and can be
inconvenient to enter in the default decimal representation. So various other
representations are permitted.
Multiplicative suffixes are accepted. They are one, two or three letter strings appended
directly after the number to which they apply:
c C *1
w W *2
b B *512
k K KiB *1024
KB *1000
m M MiB *1048576
MB *1000000
g G GiB *(2^30)
GB *(10^9)
t T TiB *(2^40)
TB *(10^12)
p P PiB *(2^50)
PB *(10^15)
An example is "2k" for 2048. The large tera and peta suffixes are only available for
numeric arguments that might require 64 bits to represent internally.
A suffix of the form "x<n>" multiplies the leading number by <n>. An example is "2x33" for
"66". The leading number cannot be "0" (zero) as that would be interpreted as a
hexadecimal number (see below).
These multiplicative suffixes are compatible with GNU's dd command (since 2002) which
claims compliance with SI and with IEC 60027-2.
Alternatively numerical arguments can be given in hexadecimal. There are two syntaxes. The
number can be preceded by either "0x" or "0X" as found in the C programming language. The
second hexadecimal representation is a trailing "h" or "H" as found in (storage)
standards. When hex numbers are given, multipliers cannot be used. For example the decimal
value "256" can be given as "0x100" or "100h".
SCRIPTS, EXAMPLES and UTILS
There are several bash shell scripts in the 'scripts' subdirectory that invoke compiled
utilities (e.g. sg_readcap). The scripts start with 'scsi_' rather than 'sg_'. One purpose
of these scripts is to call the same utility (e.g. sg_readcap) on multiple disks. Most of
the basic compiled utilities only allow one device as an argument. Some distributions
install these scripts in a visible directory (e.g. /usr/src/bin). Some of these scripts
have man page entries. See the README file in the 'scripts' subdirectory.
There is some example C code plus examples of complex invocations in the 'examples'
subdirectory. There is also a README file. The example C may be a simpler example of how
to use a SCSI pass-through in Linux than the main utilities (found in the 'src'
subdirectory). This is due to the fewer abstraction layers (e.g. they don't worry the
MinGW in Windows may open a file in text rather than binary mode).
Some utilities that the author has found useful have been placed in the 'utils'
subdirectory.
WEB SITE
There is a web page discussing this package at http://sg.danny.cz/sg/sg3_utils.html . The
device naming used by this package on various operating systems is discussed at:
http://sg.danny.cz/sg/device_name.html .
AUTHORS
Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and
individual source files (in the 'src' directory).
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 1999-2013 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 contain the most reusable code, namely sg_lib.[hc], sg_cmds_basic.[hc]
and sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty; not even for
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
SEE ALSO
sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)