sg3_utils
(1m)
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 SG3_UTILS(8)
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 pro-
vided 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
sg3_utils-1.32 Last change: January 2012 1
SG3_UTILS SG3_UTILS(8)
the short form and a "=" in the longer form (e.g. in the
sg_verify utility '-l 2a6h' and '--lba=2a6h' are equiva-
lent). 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 "-" fol-
lowed 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 utili-
ties 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 back-
ward 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"
sg3_utils-1.32 Last change: January 2012 2
SG3_UTILS SG3_UTILS(8)
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 "Physi-
calDrive<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 Win-
dows blocks attempts to use it if a class driver has
"claimed" the device. There are SCSI device types (e.g. Au-
tomation/Drive interface type) for which there is no class
driver. At least two transports ("bus types" in Windows jar-
gon): 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 pack-
age.
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 parti-
tions on it. Disk partitions that are not recognised by Win-
dows are not usually given a volume name. However Vista does
show a volume name for a disk which has no partitions recog-
nised by it and when selected invites the user to format it
(which may be rather unfriendly to other OSes).
sg3_utils-1.32 Last change: January 2012 3
SG3_UTILS SG3_UTILS(8)
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 fol-
lowing "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 fol-
lowing 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 direc-
tory. Tape drives appear in the /dev/rmt directory.
sg3_utils-1.32 Last change: January 2012 4
SG3_UTILS SG3_UTILS(8)
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 opera-
tion 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 cor-
rupted block on a disk will yield this value.
5 the DEVICE reports an "illegal request" with an addi-
tional 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 addi-
tional sense code of "invalid command operation code"
which means that it doesn't support the requested
sg3_utils-1.32 Last change: January 2012 5
SG3_UTILS SG3_UTILS(8)
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, proba-
bly leaving the utility with an exit status of 0 .
33 the command sent to DEVICE has timed out.
97 the response to a SCSI command 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 repeat-
able (an example of one that is not is "unit attention") so
the utility can be run again with the '-v' option (or sev-
eral) 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 mes-
sage).
Some options are used uniformally in most of the utilities
in this package. Those options are listed below. Note that
there are some exceptions.
sg3_utils-1.32 Last change: January 2012 6
SG3_UTILS SG3_UTILS(8)
-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 ver-
bosity. 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 inconve-
nient to enter in the default decimal representation. So
sg3_utils-1.32 Last change: January 2012 7
SG3_UTILS SG3_UTILS(8)
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 suf-
fixes 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 can-
not be "0" (zero) as that would be interpreted as a hexadec-
imal 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 hexadeci-
mal. 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 Bourne shell scripts in the 'scripts' sub-
directory that invoke compiled utilities (e.g. sg_readcap).
The scripts start with 'scsi_' rather than 'sg_'. One pur-
pose 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 distri-
butions 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.
sg3_utils-1.32 Last change: January 2012 8
SG3_UTILS SG3_UTILS(8)
There is some example C code plus examples of complex invo-
cations 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 Win-
dows 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 system is dis-
cussed in the page: http://sg.danny.cz/sg/device_name.html .
AUTHORS
Written by Douglas Gilbert. Some utilities have been con-
tributed, see the CREDITS file and individual source files
(in the 'src' directory).
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 1999-2012 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 MER-
CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Uncommitted |
+---------------+--------------------------+
SEE ALSO
sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
sg3_utils-1.32 Last change: January 2012 9
SG3_UTILS SG3_UTILS(8)
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://sg.danny.cz/sg/p/sg3_utils-1.33.tgz
Further information about this software can be found on the
open source community website at
http://sg.danny.cz/sg/sg3_utils.html.
sg3_utils-1.32 Last change: January 2012 10