sg3_utils - a package of utilities for sending SCSI commands
] [ --maxlen=LEN
] [ OTHER_OPTIONS
sg3_utils is a package of utilities that send SCSI commands to the given
via a SCSI pass through interface provided by the host operating
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. The sg_raw
utility can be used to send an arbitrary SCSI command (supplied on the command
line) to the given DEVICE
sg_decode_sense can be used to decode SCSI sense data given on the command line
or in a file. sg_raw -vvv will output the T10 name of a given SCSI CDB which
is most often 16 bytes or less in length.
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
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
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.
Most 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 it
has become more common for many other disks (including SATA disks and USB
storage devices) 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.
Very little has changed in Linux device naming in the Linux kernel 3 and 4
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.
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 class and
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
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.
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:
- syntax error. Either illegal command line options, options
with bad arguments or a combination of options that is not permitted.
- 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. In Linux the DEVICE may be temporarily blocked while error
recovery is taking place.
- 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.
- 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.
- 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.
- the DEVICE reports a "data protect" sense
key. This implies some mechanism has blocked writes (or possibly all
access to the media).
- 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.
- the DEVICE reports a "copy aborted". This
implies another command or device problem has stopped a copy operation.
The EXTENDED COPY family of commands (including WRITE USING TOKEN) may
return this sense key.
- 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).
- the DEVICE reports a miscompare sense key. VERIFY
and COMPARE AND WRITE commands may report this.
- the utility is unable to open, close or use the given
DEVICE or some other file. The given file name could be incorrect
or there may be permission problems. Adding the '-v' option may give more
- 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. There may be useful information in the sense data such as a
- 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 .
- the DEVICE reports a SCSI status of
"reservation conflict". This means access to the DEVICE
with the current command has been blocked because another machine (HBA or
SCSI "initiator") holds a reservation on this DEVICE. On
modern SCSI systems this is related to the use of the PERSISTENT
RESERVATION family of commands.
- the DEVICE reports a SCSI status of "condition
met". Currently only the PRE-FETCH command (see SBC-4) yields this
- the DEVICE reports a SCSI status of
"busy". SAM-5 defines this status as the logical unit is
temporarily unable to process a command. It is recommended to re-issue the
- the DEVICE reports a SCSI status of "task set
- the DEVICE reports a SCSI status of "ACA
active". ACA is "auto contingent allegiance" and is seldom
- the DEVICE reports a SCSI status of "task
aborted". SAM-5 says: "This status shall be returned if a
command is aborted by a command or task management function on another I_T
nexus and the Control mode page TAS bit is set to one".
- the command sent to DEVICE has timed out.
- the command sent to DEVICE has received an
"aborted command" sense key with an additional sense code of
0x10. This group is related to problems with protection information (PI or
DIF). For example this error may occur when reading a block on a drive
that has never been written (or is unmapped) if that drive was formatted
with type 1, 2 or 3 protection.
- a SCSI command response failed sanity checks.
- the DEVICE reports it has a check condition but the
error doesn't fit into any of the above categories.
- 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.
- the utility was found but could not be executed. That might
occur if the executable does not have execute permissions.
- This is the exit status for utility not found. That might
occur when a script calls a utility in this package but the PATH
environment variable has not been properly set up, so the script cannot
find the executable.
- 128 + <signum>
- If a signal kills a utility then the exit status is 128
plus the signal number. For example if a segmentation fault occurs then a
utility is typically killed by SIGSEGV which according to 'man 7 signal'
has an associated signal number of 11; so the exit status will be 139
- the utility tried to yield an exit status of 255 or larger.
That should not happen; given here for completeness.
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.
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.
- -e, --enumerate
- some utilities (e.g. sg_ses and sg_vpd) store a lot of
information in internal tables. This option will output that information
in some readable form (e.g. sorted by an acronym or by page number) then
exit. Note that with this option DEVICE is ignored (as are most
other options) and no SCSI IO takes place, so the invoker does not need
any elevated permissions.
- -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. To produce hexadecimal that can be
parsed by other utilities (e.g. without a relative address to the left and
without trailing ASCII) use this option three or four times.
- -i, --in=FN
- many SCSI commands fetch a significant amount of data
(returned in the data-in buffer) which several of these utilities decode
(e.g. sg_vpd and sg_logs). To separate the two steps of fetching the data
from a SCSI device and then decoding it, this option has been added. The
first step (fetching the data) can be done using the --hex or
--raw option and redirecting the command line output to a file
(often done with ">" in Unix based operating systems). The
difference between --hex and --raw is that the former
produces output in ASCII hexadecimal while --raw produces its
output in "raw" binary.
The second step (i.e. decoding the SCSI response data now held in a file)
can be done using this --in=FN option where the file name is
FN. If "-" is used for FN then stdin is assumed,
again this allows for command line redirection (or piping). That file (or
stdin) is assumed to contain ASCII hexadecimal unless the --raw
option is also given in which case it is assumed to be binary. Notice that
the meaning of the --raw option is "flipped" when used
with --in=FN to act on the input, typically it acts on the output
Since the structure of the data returned by SCSI commands varies
considerably then the usage information or manpage of the utility being
used should be checked. In some cases --hex may need to be used
multiple times (and is more conveniently given as '-HH' or '-HHH). In
other cases the name of this option is --inhex=FN.
- -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 so as to not interfere with the
output from this option.
Some utilities that consume data to send to the DEVICE along with the
SCSI command, use this option. Alernatively the --in=FN option
causes DEVICE to be ignored and the response data (to be decoded)
fetched from a file named FN. In these cases this option may
indicate that binary data can be read from stdin or from a nominated file
- -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.
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
m M MiB *1048576
g G GiB *(2^30)
t T TiB *(2^40)
p P PiB *(2^50)
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
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".
There are two standardized methods for downloading microcode (i.e. device
firmware) to a SCSI device. The more general way is with the SCSI WRITE BUFFER
command, see the sg_write_buffer utility. SCSI enclosures have their own
method based on the Download microcode control/status diagnostic page, see the
There are several bash shell scripts in the 'scripts' subdirectory that invoke
compiled utilities (e.g. sg_readcap). Several of 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 devices. Most of the basic compiled
utilities only allow one device as an argument. Some distributions install
these scripts in a more visible directory (e.g. /usr/bin). Some of these
scripts have man page entries. See the README file in the 'scripts'
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'
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:
Written by Douglas Gilbert. Some utilities have been contributed, see the
CREDITS file and individual source files (in the 'src' directory).
Report bugs to <dgilbert at interlog dot com>.
Copyright © 1999-2016 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
sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)