| SG3_UTILS(8) | SG3_UTILS | SG3_UTILS(8) |
sg3_utils - a package of utilities for sending SCSI commands
sg_* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN] [--maxlen=LEN] [--raw] [--timeout=SECS] [--verbose] [--version] [OTHER_OPTIONS] DEVICE
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. The sg_raw utility can be used to send an arbitrary SCSI command (supplied on the command line) to the given DEVICE.
sg_decode_sense can be used to decode SCSI sense data given on the command line or in a file. sg_raw -vvv will output the T10 name of a given SCSI CDB which is most often 16 bytes or less in length.
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. The highest level (i.e. most abstract) document is the SCSI Architecture Model (SAM) with SAM-5 being the most recent standard (ANSI INCITS 515-2016) with the most recent draft being SAM-6 revision 4 . SCSI commands in common with all device types can be found in SCSI Primary Commands (SPC) of which SPC-4 is the most recent standard (ANSI INCITS 513-2015). The most recent SPC draft is SPC-5 revision 21. Block device specific commands (e.g. as used by disks) are in SBC, those for tape drives in SSC, those for SCSI enclosures in SES 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, SAT-2 and SAT-3) are now standards at INCITS(ANSI) and ISO while SAT-4 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 operation. 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, including as sg_inq, sg_logs, sg_modes, sg_opcode, sg_rbuff, sg_readcap, sg_senddiag, sg_start and sg_turs 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. The getopt_long() is a GNU extension (i.e. not yet POSIX certified) but more recent command line utilities tend to use it. 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.
The SG3_UTILS_OLD_OPTS environment variable is explained in the previous section. It is only for backward compatibility of the command line options for older utilities.
The SG3_UTILS_DSENSE environment variable may be set to a number. It is only used by the embedded SNTL within the library used by the utilities in this library. SNTL is a SCSI to NVMe Translation Layer. This environment variable defaults to 0 which will lead to any utility that issues a SCSI command that is translated to a NVMe command (by the embedded SNTL) that fails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this variable is non-zero then then the returned SCSI sense will be in 'descriptor' format.
Several utilities have their own environment variable setting (e.g. sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man pages for more information.
There is a Linux specific environment variable called SG3_UTILS_LINUX_NANO that if defined and the sg driver in the system is 4.0.30 or later, will show command durations in nanoseconds rather than the default milliseconds. Command durations are typically only shown if --verbose is used 3 or more times. Due to an interface problem (a 32 bit integer that should be 64 bits with the benefit of hindsight) the maximum duration that can be represented in nanoseconds is about 4.2 seconds. If longer durations may occur then don't define this environment variable (or undefine it).
Most 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 it has become more common for many other disks (including SATA disks and USB storage devices) 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" 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.
Very little has changed in Linux device naming in the Linux kernel 3 and 4 series.
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).
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.
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.
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 recognized by Windows are not usually given a volume name. However Vista does show a volume name for a disk which has no partitions recognized by it and when selected invites the user to format it (which may be rather unfriendly to other OSes).
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.
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 class and pass-through names.
FreeBSD allows device names to be given without the leading "/dev/" (e.g. da0 instead of /dev/da0). That worked in this package up until version 1.43 when the unadorned device name (e.g. "da0") gave an error. The original action (i.e. allowing unadorned device names) has been restored in version 1.46 . Also note that symlinks (to device names) are followed before prepending "/dev/" if the resultant name doesn't start with a "/".
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.
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 .
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 directory. Tape drives appear in the /dev/rmt directory.
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.
NVMe (or NVM Express) is a relatively new storage transport and command set. The level of abstraction of the NVMe command set is somewhat lower the SCSI command sets, closer to the level of abstraction of ATA (and SATA) command sets. NVMe claims to be designed with flash and modern "solid state" storage in mind, something unheard of when SCSI was originally developed in the 1980s.
The SCSI command sets' advantage is the length of time they have been in place and the existing tools (like these) to support it. Plus SCSI command sets level of abstraction is both and advantage and disadvantage. Recently the NVME-MI (Management Interface) designers decide to use the SCSI Enclosure Services (SES-3) standard "as is" with the addition of two tunnelling NVME-MI commands: SES Send and SES Receive. This means after the OS interface differences are taken into account, the sg_ses, sg_ses_microcode and sg_senddiag utilities can be used on a NVMe device that supports a newer version of NVME-MI.
The NVME-MI SES Send and SES Receive commands correspond to the SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands respectively. There are however a few other commands that need to be translated, the most important of which is the SCSI INQUIRY command to the NVMe Identify controller/namespace. Starting in version 1.43 these utilities contain a small SNTL (SCSI to NVMe Translation Layer) to take care of these details.
As a side effect of this "juggling" if the sg_inq utility is used (without the --page= option) on a NVMe DEVICE then the actual NVMe Identifier (controller and possibly namespace) responses are decoded and output. However if 'sg_inq --page=sinq <device>' is given for the same DEVICE then parts of the NVMe Identify controller and namespace response are translated to a SCSI standard INQUIRY response which is then decoded and output.
Apart from the special case with the sg_inq, all other utilities in the package assume they are talking to a SCSI device and decode any response accordingly. One easy way for users to see the underlying device is a NVMe device is the standard INQUIRY response Vendor Identification field of "NVMe " (an 8 character long string with 4 spaces to the right).
The following SCSI commands are currently supported by the SNTL library: INQUIRY, MODE SELECT(10), MODE SENSE(10), READ(10,16), READ CAPACITY(10,16), RECEIVE DIAGNOSTIC RESULTS, REQUEST SENSE, REPORT LUNS, REPORT SUPPORTED OPERATION CODES, REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS, SEND DIAGNOSTICS, START STOP UNIT, SYNCHRONIZE CACHE(10,16), TEST UNIT READY, VERIFY(10,16), WRITE(10,16) and WRITE SAME(10,16).
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 listed below can be given to the
sg_decode_sense utility (which is found in this package) as follows:
sg_decode_sense --err=<exit_status>
and a short explanatory string will be output to stdout.
The exit status values are:
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.
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).
Some options are used uniformly in most of the utilities in this package. Those options are listed below. Note that there are some exceptions.
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 kB *1000
m M MiB *1048576
MB mB *1000000
g G GiB *(2^30)
GB 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.
These multiplicative suffixes are compatible with GNU's dd command (since 2002) which claims compliance with SI and with IEC 60027-2.
A suffix of the form "x<n>" multiplies the preceding number by <n>. An example is "2x33" for "66". The left argument cannot be '0' as '0x' will be interpreted as hexadecimal number prefix (see below). The left argument to the multiplication must end in a hexadecimal digit (i.e. 0 to f) and the whole expression cannot have any embedded whitespace (e.g. spaces). An ugly example: "0xfx0x2" for 30.
A suffix of the form "+<n>" adds the preceding number to <n>. An example is "3+1k" for "1027". The left argument to the addition must end in a hexadecimal digit (i.e. 0 to f) and the whole expression cannot have any embedded whitespace (e.g. spaces). Another example: "0xf+0x2" for 17.
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".
Such a file is assumed to contain a sequence of one or two digit ASCII hexadecimal values separated by whitespace. "Whitespace consists of either spaces, tabs, blank lines, or any combination thereof". Each one or two digit ASCII hex pair is decoded into a byte (i.e. 8 bits). The following will be decoded to valid (ascending valued) bytes: '0', '01', '3', 'c', 'F', '4a', 'cC', 'ff'. Lines containing only whitespace are ignored. The contents of any line containing a hash mark ('#') is ignored from that point until the end of that line. Users are encouraged to use hash marks to introduce comments in hex files. The author uses the extension'.hex' on such files. Examples can be found in the 'inhex' directory.
There are two standardized methods for downloading microcode (i.e. device firmware) to a SCSI device. The more general way is with the SCSI WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclosures have their own method based on the Download microcode control/status diagnostic page, see the sg_ses_microcode utility.
There are several bash shell scripts in the 'scripts' subdirectory that invoke compiled utilities (e.g. sg_readcap). Several of 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 devices. Most of the basic compiled utilities only allow one device as an argument. Some distributions install these scripts in a more visible directory (e.g. /usr/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.
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 systems is discussed at: http://sg.danny.cz/sg/device_name.html . There is a git code mirror at https://github.com/hreinecke/sg3_utils . The principle code repository uses subversion and is on the author's equipment. The author keeps track of this via the subversion revision number which is an ascending integer (currently at 774 for this package). The github mirror gets updated periodically from the author's repository. Depending on the time of update, the above Downloads section at sg.danny.cz may be more up to date than the github mirror.
Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and individual source files (in the 'src' directory).
Report bugs to <dgilbert at interlog dot com>.
Copyright © 1999-2021 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.
| March 2021 | sg3_utils-1.46 |