sg3_utils(8) - phpMan

SG3_UTILS(8) SG3_UTILS SG3_UTILS(8)

NAME
sg3_utils - a package of utilities for sending SCSI commands

SYNOPSIS
sg_* [--help] [--hex] [--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 drives in
MMC.

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 func-
tion, 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 (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 sg_modes).
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 util-
ities 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 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 to which they correspond. 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 some-
thing unrelated to the requested command has occurred (e.g. a device reset) poten-
tially 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 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 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).

-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.

-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.

AUTHORS
Written by Douglas Gilbert.

REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
Copyright (C) 1999-2007 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 utili-
ties 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.