doc/sg3_utils.8

.TH SG3_UTILS "8" "December 2010" "sg3_utils\-1.31" SG3_UTILS
.SH NAME
sg3_utils \- a package of utilities for sending SCSI commands
.SH SYNOPSIS
.B sg_*
[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR]
[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fIOTHER_OPTIONS\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
sg3_utils is a package of utilities that send SCSI commands to the given
\fIDEVICE\fR via a SCSI pass through interface provided by the host
operating system.
.PP
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.
.PP
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/HD_DVD/BD drives in MMC.
.PP
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.
.PP
There is some support for SCSI tape devices but not for their basic
commands. The reader is referred to the "mt" utility.
.PP
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 \fIDEVICE\fR argument may appear after, between or prior to any options.
.PP
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).
.PP
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.
.PP
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.
.SH 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 ).
.PP
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.
.PP
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.
.PP
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.
.SH 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).
.PP
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.
.PP
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.
.PP
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 recognised by Windows are not usually given a volume name. However
Vista does show a volume name for a disk which has no partitions recognised
by it and when selected invites the user to format it (which may be rather
unfriendly to other OSes).
.PP
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.
.PP
The sg_scan utility lists out Windows device names in forms that are
suitable for other utilities in this package to use.
.SH 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.
.SH 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.
.PP
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 .
.PP
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.
.PP
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.
.PP
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 .
.PP
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.
.SH 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:
.TP
.B 0
success
.TP
.B 1
syntax error. Either illegal command line options, options with bad
arguments or a combination of options that is not permitted.
.TP
.B 2
the \fIDEVICE\fR 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.
.TP
.B 3
the \fIDEVICE\fR 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.
.TP
.B 5
the \fIDEVICE\fR 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.
.TP
.B 6
the \fIDEVICE\fR 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.
.TP
.B 9
the \fIDEVICE\fR reports an illegal request with an additional sense code
of "invalid command operation code" which means that it doesn't support the
requested command.
.TP
.B 11
the \fIDEVICE\fR reports an aborted command. In some cases aborted
commands can be retried immediately (e.g. if the transport aborted
the command due to congestion).
.TP
.B 15
the utility is unable to open, close or use the given \fIDEVICE\fR.
The given file name could be incorrect or there may be permission
problems. Adding the '\-v' option may give more information.
.TP
.B 20
the \fIDEVICE\fR 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.
.TP
.B 21
the \fIDEVICE\fR 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 .
.TP
.B 33
the command sent to \fIDEVICE\fR has timed out.
.TP
.B 97
the response to a SCSI command failed sanity checks.
.TP
.B 98
the \fIDEVICE\fR reports it has a check condition but the error
doesn't fit into any of the above categories.
.TP
.B 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.
.PP
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.
.SH 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).
.PP
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).
.TP
\fB\-h\fR, \fB\-?\fR, \fB\-\-help\fR
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.
.TP
\fB\-H\fR, \fB\-\-hex\fR
for SCSI commands that yield a non\-trivial response, print out that
response in ASCII hexadecimal.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
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.
.TP
\fB\-r\fR, \fB\-\-raw\fR
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.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
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.
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit. Each utility has its own version
number and date of last code change.
.SH 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.
.PP
Multiplicative suffixes are accepted. They are one, two or three letter
strings appended directly after the number to which they apply:
.PP
   c C         *1
.br
   w W         *2
.br
   b B         *512
.br
   k K KiB     *1024
.br
   KB          *1000
.br
   m M MiB     *1048576
.br
   MB          *1000000
.br
   g G GiB     *(2^30)
.br
   GB          *(10^9)
.br
   t T TiB     *(2^40)
.br
   TB          *(10^12)
.br
   p P PiB     *(2^50)
.br
   PB          *(10^15)
.PP
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.
.PP
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).
.PP
These multiplicative suffixes are compatible with GNU's dd command (since
2002) which claims compliance with SI and with IEC 60027\-2.
.PP
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".
.SH SCRIPTS, EXAMPLES and UTILS
There are several bourne 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.
.PP
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).
.PP
Some utilities that the author has found useful have been placed in
the 'utils' subdirectory.
.SH 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 discussed in the page:
http://sg.danny.cz/sg/device_name.html .
.SH AUTHORS
Written by Douglas Gilbert. Some utilities have been contributed, see the
CREDITS file and individual source files (in the 'src' directory).
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 1999\-2011 Douglas Gilbert
.br
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.
.SH "SEE ALSO"
.B sdparm(sdparm), sg_scan(sg3_utils), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)