Content-type: text/html Man page of SG3_UTILS

SG3_UTILS

Section: SG3_UTILS (8)
Updated: February 2010
Index Return to Main Contents

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

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

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.

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

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.

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

WEB SITE

There is a web page discussing this package at http://sg.danny.cz/sg/sg3_utils.html .

AUTHORS

Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and individual source files (in the 'src' directory).

REPORTING BUGS

Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

Copyright © 1999-2010 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 PARTICULAR PURPOSE.

This document was created by man2html, using the manual pages.
Time: 21:23:02 GMT, April 06, 2010