SG3UTILS SG3UTILS(1M)
NAME
sg3utils - a package of utilities for sending SCSI commands
SYNOPSIS
sg* [--help] [--hex] [--maxlen=LEN] [--raw] [--verbose]
[--version] [OTHEROPTIONS] DEVICE
DESCRIPTION
sg3utils 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 "sgverify" utility sends the SCSI VERIFY command. A
mapping between SCSI commands and the sg3utils 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 SC and those for
CD/DVD/HDVD/BD drives in MC.
There are two generations of command line option usage. The
newer utilities (written since July 2004) use the
getoptlong() 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
sgverify utility '-l 2a6h' and '--lba=2a6h' are
equivalent). Note that with getoptlong(), 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 sginq, had individual command
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 sgmodes with its older interface). Various
options can be elided as long as it is not ambiguous (e.g.
'-vv' to increase the verbosity).
sg3utils-1.26 Last change: April 2008 1
SG3UTILS SG3UTILS(1M)
Over time the command line interface of these older utili-
ties became messy and overloaded with options. So in
sg3utils version 1.23 the command line interface of these
older utilities was altered to have both a cleaner
getoptlong() interface and their older interface for back-
ward compatibility. By default these older utilities use
their getoptlong() based interface. That can be overridden
by defining the SG3UTILSOLDOPTS environment variable or
using '-O' or '--old' as the first command line option. The
man pages of the older utilities documents the details.
Several sg3utils utilities are based on the Unix dd command
(e.g. sgdd) and share dd's 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. 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 dev-
ice. Note that unit attention conditions are usually
only reported once by a device.
sg3utils-1.26 Last change: April 2008 2
SG3UTILS SG3UTILS(1M)
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 com-
mand.
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, prob-
ably 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
several) to obtain more information.
COMON 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).
sg3utils-1.26 Last change: April 2008 3
SG3UTILS SG3UTILS(1M)
-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 ASCI 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 sglogs(1M) 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 verbos-
ity. 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.
AUTHORS
Written by Douglas Gilbert.
REPORTING BUGS
Report bugs to .
sg3utils-1.26 Last change: April 2008 4
SG3UTILS SG3UTILS(1M)
COPYRIGHT
Copyright O 1999-2008 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 sglib.[hc],
sgcmdsbasic.[hc] and sgcmdsextra.[hc] are under a
FreeBSD license. There is NO warranty; not even for MERCHAN-
TABILITY or FITNES FOR A PARTICULAR PURPOSE.
SEE ALSO
sdparm(sdparm)
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWsg3utilsu
Interface Stability Committed
NOTES
Source for sg3utils is available on http:/opensolaris.org.
sg3utils-1.26 Last change: April 2008 5
|
