The Linux sg3_utils package

The Linux sg3_utils package

Introduction

The sg3_utils package contains utilities that send SCSI commands to devices. As well as devices on transports traditionally associated with SCSI (e.g. Fibre Channel (FCP), Serial Attached SCSI (SAS) and the SCSI Parallel Interface(SPI)) many other devices use SCSI command sets. ATAPI cd/dvd drives and SATA disks that connect via a translation layer or a bridge device are examples of devices that use SCSI command sets.

SCSI command sets are divided into a common set and several device class specific sets. The common set of commands is referred to as the SCSI Primary Commands (SPC) with SPC-3 being the most recent standard. The mandatory SCSI INQUIRY command is defined in SPC-3. The SCSI Block Commands (SBC) cover direct access devices such as disks. The MultiMedia Commands (MMC) cover CD and DVD drives and the media within them. SCSI command sets and transport definitions can be found at the www.t10.org . That site includes this helpful diagrammatic overview: www.t10.org/scsi-3.htm .

The sg3_utils package was developed for the linux kernel 2.4 and 2.6 series and is still being enhanced. An earlier package called sg_utils targeted the linux kernel 2.2 series with some support for the 2.0 series. See an earlier version of this web page for further information about sg_utils. This document describes version 1.28 of sg3_utils . The majority of these utilities have been ported to the FreeBSD, Solaris, Tru64 and the Windows operating systems.

In the linux kernel 2.4 series most of these utilities must be used with a SCSI generic (sg) driver device name (e.g. /dev/sg0). In the lk 2.6 series almost all of these utilities can be used with the primary device names as well (e.g. /dev/sda, /dev/scd0, /dev/st0 and /dev/hdd (if it is an ATAPI device)).

A list of SCSI and storage utility programs can be found on this tools page.

Contents of sg3_utils

This package contains over 30 utilities, their "man" pages, build files and general documentation (e.g. several README files). The utilities have a command line interface which in general has this form:

UTILITY_NAME [OPTIONS] DEVICE

No more than one DEVICE name can be given (and in a few cases, no DEVICE name is required). Below is a listing in alphabetical order of the utilities in the sg3_utils package:

Table 1 Utilities in sg3_utils
Utility	Main SCSI commands invoked	directory	CLI	Ported	Notes
hxascdmp	-	utils	adhoc	f,s,w	converts stdin (assumed binary) to ASCII hex and ASCII, sending its output to stdout (like the Unix od command and hexdump in BSD)
rescan-scsi-bus.sh	-	archive	adhoc		copy of Kurt Garloff's useful script
scsi_inquiry	INQUIRY	examples	adhoc		uses deprecated SCSI_IOCTL_SEND_COMMAND ioctl
sdparm	MODE SENSE/SELECT, INQUIRY	-->	getopt	f,s,t,w	was in the sg3_utils package for a short time; now in own package, see sdparm . sdparm manipulates mode pages, reads VPD pages and sends simple commands.
sg_chk_asc	-	utils	getopt	f,s	check asc/ascq codes from www.t10.org page against sg3_utils table
sginfo [legacy, use sdparm]	MODE SENSE/SELECT, READ DEFECT	src	adhoc		symbolic decoding (optional changing) of mode pages. Can also output (disk) defect lists. Port of older scsiinfo utility.
sgm_dd	READ, WRITE	src	dd		sg_dd variant that uses memory mapped IO (only on linux sg devices)
sgp_dd	READ, WRITE	src	dd		sg_dd variant that uses POSIX threads
sg_dd	READ, WRITE	src	dd		Unix dd command variant, uses SG_IO ioctl to send SCSI commands to copy data. See the sg_dd page. Reworked to ddpt .
sg_emc_trespass	MODE SELECT	src	adhoc		utility specialized for EMC Clariion series
sg_format	FORMAT	src	getopt	f,s,t,w	format or resize a SCSI disk
sg_get_config	GET CONFIGURATION	src	getopt	f,s,t,w	fetch features and profiles of a cd/dvd drive and/or its current media
sg_get_lba_status	GET LBA STATUS	src	getopt	f,s,t,w	thin provisioning support
sg_ident	REPORT/SET IDENTIFYING INFORMATION	src	getopt	f,s,t,w	default is to report (fetch) the device identifier. With the '--set' option a new identifier is sent to the device.
sg_inq	INQUIRY	src	getopt+	f,s,t,w	fetch standard response, VPD pages or version descriptors. Also can perform IDENTIFY (PACKET) DEVICE ATA command. VPD page decoding also performed by sg_vpd and sdparm.
sg_logs	LOG SENSE	src	getopt+	f,s,t,w	fetch log sense pages, decode standard and some vendor pages
sg_luns	REPORT LUNS	src	getopt	f,s,t,w	fetch luns reported by a device (lun 0 or "well known lu")
sg_map	INQUIRY	src	adhoc		shows mapping between sg devices and primary device node (if any). In lk 2.6 see lsscsi .
sg_map26		src	getopt		maps between single linux sg device and primary device node (and vice versa). Also does mapping in to, and out of, sysfs. For the linux 2.6 series.
sg_modes	MODE SENSE	src	getopt+	f,s,t,w	fetch mode pages (output mainly in hex, to decode output use sdparm)
sg_opcodes	REPORT SUPPORTED OPERATION CODES	src	getopt+	f,s,t,w	fetch supported SCSI commands or supported task management functions
sg_persist	PERSISTENT RESERVE IN/OUT	src	getopt	f,s,t,w	control persistent reservations and report reservation status
sg_prevent	PREVENT ALLOW MEDIUM REMOVAL	src	getopt	f,s,t,w	control media removal, mainly for those SCSI devices which have removable media (e.g. CD/DVD and tape drives)
sg_raw	<user specified>	src	getopt	f,s,t,w	send user supplied cdb
sg_rbuf	READ BUFFER	src	getopt+		read from SCSI device cache. Typically for testing the SCSI transport (for throughput or errors)
sg_rdac	MODE SENSE/SELECT	src	adhoc	f,s,t,w	display or modify RDAC redundant controller mode page
sg_read	READ	src	dd		read continually from same offset. Syntax similar to sg_dd (without write side). Can test SCSI device cache and transport performance.
sg_readcap	READ CAPACITY	src	getopt+	f,s,t,w	fetch the number of blocks and the individual block size for disks and CD/DVD media
sg_read_buffer	READ BUFFER	src	getopt	f,s,t,w	read descriptors or data
sg_read_long	READ LONG	src	getopt	f,s,t,w	read data from given lba which includes the block and ECC data.
sg_reassign	REASSIGN BLOCKS	src	getopt	f,s,t,w	reassign a lba from one sector on a disk (typically damaged) to a new (spare) sector. User data copied if it is recoverable.
sg_requests	REQUEST SENSE	src	getopt	f,s,t,w	fetch sense data from the given device. Modern uses include getting a progress indication (e.g. during a format) or finding the power condition state.
sg_reset	-	src	adhoc		Issue a driver, (SCSI) bus or device (target or lun?) reset.
sg_rmsn	READ MEDIA SERIAL NUMBER	src	getopt	f,s,t,w	Relatively new command added to SPC-3. Format of response is vendor specific so this utility outputs it in hex (default) or binary.
sg_rtpg	REPORT TARGET PORT GROUPS	src	getopt	f,s,t,w	Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others).
sg_safte	READ BUFFER	src	getopt	f,s,t,w	fetch information from a SAF-TE processor
sg_sat_identify	ATA PASS-THROUGH	src	getopt	f,s,t,w	Send ATA IDENTIFY DEVICE or IDENTIFY PACKET DEVICE commands via the SAT ATA PASS-THROUGH (16 or 12) SCSI command.
sg__sat_identify	ATA PASS-THROUGH	examples	adhoc		Simpler version of sg_sat_identify that uses the linux SG_IO ioctl directly. See also sg_sat_chk_power, sg_sat_phy_event, sg__sat_set_features and sg_sat_smart_rd_data in the examples subdirectory.
sg_sat_phy_event	ATA PASS-THROUGH	src	getopt	f,s,t,w	Sends an ATA READ LOG EXT command via a SAT to fetch log page 11h which contains SATA phy event counters.
sg__sat_phy_event	ATA PASS-THROUGH	examples	getopt		Simpler version of sg_sat_phy_event
sg_sat_set_features	ATA PASS_THROUGH	src	getopt	f,s,t,w	Sends ATA SET FEATURES command via SAT
sg__sat_set_features	ATA PASS_THROUGH	examples	getopt		Simpler version of sg_sat_set_features that uses the linux SG_IO ioctl directly.
sg_scan	[INQUIRY]	src .c.linux	adhoc	linux only	maps each sg device name to the corresponding numeric <host, channel, target, lun> tuple. In lk 2.6 series the "lsscsi -g" command is similar.
sg_scan	[INQUIRY]	src .c.win32	getopt	win32 only	shows one device per line, with the device's various names and INQUIRY response string on that line.
sg_senddiag	SEND DIAGNOSTIC	src	getopt+	f,s,t,w	Issues either a default self test or a short/extended foreground/background self test. With no arguments it uses RECEIVE DIAGNOSTIC RESULTS to list all supported diagnostic pages.
sg_ses	SEND/RECEIVE DIAGNOSTIC	src	getopt	f,s,t,w	Fetches status diagnostic pages from, and sends some control pages to, a SCSI Enclosure Services (SES) device.
sg_simple1,2,3,4,5	INQUIRY, TEST UNIT READY	examples	adhoc		Simple code examples of using the scsi generic (sg) driver interface
sg_simple16	READ	examples	adhoc		Simple code example of sending a 16 byte cdb SCSI READ command
sg_start	START STOP UNIT	src	getopt+	f,s,t,w	Controls the power condition state of a SCSI device. Primary use is to spin up and down SCSI disks. Can also load and eject removable media.
sg_stpg	SET TARGET PORT GROUPS	src	getopt	f,s,t,w	Specialized for multi-ported SCSI devices where one port (or a group of them) is preferred for IO over another (or others).
sg_sync	SYNCHRONIZE CACHE	src	getopt	f,s,t,w	Causes disk caches to be flushed to media
sg_test_rwbuf	READ/WRITE BUFFER	src	getopt		Random pattern written to SCSI device buffer then read back and checked. Used in testing for data corruption.
sg_turs	TEST UNIT READY	src	getopt+	f,s,t,w	Issue one or more Test Unit Ready commands. Can be used to time SCSI command overhead.
sg_unmap	UNMAP	src	getopt	f,s,t,w	thin provisioning support ("Trim" in the ATA world)
sg_verify	VERIFY	src	getopt	f,s,t,w	reads indicated blocks on a SCSI disks, stops on the first error found. Does not yield any data. Useful for media scans.
sg_vpd	INQUIRY	src	getopt	f,s,t,w	Decodes standard and some vendor Vital Product Data (VPD) pages.
sg_write_buffer	WRITE BUFFER	src	getopt	f,s,t,w	write data; can be used to download firmware
sg_write_long	WRITE LONG	src	getopt	f,s,t,w	writes to a lba, data which includes the block and ECC data. Suitable data typically fetched by prior sg_read_long utility.
sg_write_same	WRITE SAME	src	getopt	f,s,t,w	writes a single block to one or more (consecutive) lbas
sg_wr_mode	MODE SELECT	src	getopt	f,s,t,w	writes mode pages supplied in ASCII hex (e.g. from "sg_modes -r") to the SCSI device. See sdparm for another method of setting mode page parameters.

More SCSI commands may be issued than shown in the Main SCSI commands invoked column. For example many utilities issue a SCSI INQUIRY command to find out the peripheral device type of the given device. Some SCSI commands listed above are only relevant to a specific device type (e.g. FORMAT UNIT for disks) and should not be sent to a device belonging to other peripheral device types (and in some cases these utilities will block inappropriate attempts). See the COVERAGE file in the main directory of the tarball for a more exhaustive list of SCSI (and ATA) commands issued by the sg3_utils utilities.

The directory column contains the sub-directory name in which the utility source code is found. Prior to version 1.25 those utilities shown as being the src sub-directory were found in the main directory. Those utilities found in the src sub-directory are considered the main utilities which are built and installed by the infrastructure files in the main directory (e.g. a './configure ; make ; make install' sequence). Source code in other sub-directories may, in some cases, be built by Makefiles in those sub-directories. See the README file for more information. Each utility shown in the src sub-directory has a corresponding "man" page in the doc sub-directory. Some utilities in the other subdirectories have "man" pages.

The CLI column indicates what kind of Command Line Interface the utility has. Recent utilities have a CLI based on the getopt_long() function which offers both long option names (e.g. "--verbose") and a short form (e.g. '-v'). Both forms can take an argument. Experience has led to consistent use of various options such as "--help", "--verbose" and "--version" across these utilities. Utilities with this type of CLI are marked with "getopt" in the CLI column. The original utilities had an "ad hoc" type CLI that unfortunately lacked consistency and had a mix of long and short forms (with the long form sometime prefixed with "-" and on other occasions with "--"). Utilities with this type of CLI are marked with "adhoc". There is also a group of utilities that are related to the Unix dd command and share its quirky CLI. Finally a group of well used utilities with ad hoc command line interfaces had a getop_long() based interface added in sg3_utils version 1.23 . This group contains significant utilities such as sg_inq, sg_logs and sg_modes. The default CLI for this group is "getopt" but by using "--old" or "-O" as the first option the older ad hoc options can be used. This group will default to the older ad hoc interface if the environment variable SG3_UTILS_OLD_OPTS is defined. Utilities with this type of CLI are marked with "getopt+".

If the Ported column is empty then the utility is only found in Linux. Support for other ports is indicated by "f" for FreeBSD, "s" for Solaris, "t" for Tru64 (OSF), and "w" for Windows. See the README.freebsd, README.solaris, README.tru64, README.win32, and the INSTALL files for more information.

This paragraph contains Linux specific information. All utilities that issue SCSI commands and that appear in the src sub-directory of table 1, with the exception of sgp_dd, issue SG_IO ioctls. The sgp_dd utility issues SCSI commands using the sg driver's asynchronous ( write()/read() ) interface to device nodes that have the sg driver's major device number (i.e. "char" major 21). This means that all utilities in the src sub-directory are "safe" with any given device node. If the device node does not support the SG_IO ioctl then that is reported and the utility exits. [In version 1.14 and earlier, sgm_dd also use the sg driver's asynchronous ( write()/read() ) interface but that has been changed to the SG_IO ioctl in version 1.15 since the asynchronous action is not needed. sgm_dd will only use mmapp-ed IO on sg device nodes.] sg3_utils version 1.27 introduces support for bsg: the ./configure stage of the package build needs to find /usr/include/linux/bsg.h and at run time the bsg char device needs to be present in the /proc/devices pseudo file. Then if the device given to utility has a char major that matches bsg then the SG_IO ioctl is used with the sg version 4 interface.

Irrespective of the device node used to access a device, care should be taken not to interfere with a device while it is "active". For example invoking a "sg_format -F" utility on a disk with one or more of its partitions in use (e.g. a mounted file system) is obviously unwise.

Sub directories

The sg3_utils package has several sub-directories that are outlined in the following paragraphs. Prior to sg3_utils version 1.25 the Makefile in the main directory only build code from the main directory (thus, for example, it did not build the code in the examples sub-directory). From sg3_utils version 1.25 the build infrastructure files in the main directory (i.e. configure.ac and Makefile.am) only build code found in the lib, src, doc and include sub-directories.

The archive sub-directory contains code that was recently displaced from the src sub-directory. To reduce the size of the overall package, the amount of code carried forward from one release to the next is reduced from time to time.

The debian sub-directory contains rules for building a linux debian package (i.e. ".deb") from the source code in the src sub-directory. There is a build_debian.sh shell script in the main directory that can be executed to build a debian package. Note that various distributions that use debian packages and include sg3_utils may vary their build scripts from the ones supplied in this sub-directory.

The doc sub-directory contains a README file which contains urls of web documents related to sg3_utils. The html code used to be present in this sub-directory but it was bloating the package. From sg3_utils version 1.25 the source for the man pages is found in this sub-directory. Those files end with the extension ".8" indicating that they are grouped in the system administration command section. Information common to all utilities has been placed in a man page called sg3_utils.

The examples sub-directory contains relatively simple code examples that may be useful to those trying to use the SCSI pass-through mechanism in the supported operating systems. It also shows the usage of the common library code (e.g. sg_lib.c). There is also a test script and data for the sg_persist utility. There is also some test data for sg_reassign and sg_senddiag utilities; the latter test code is SAS specific.

The getopt_long sub-directory contains code for implementing the getopt_long() library call which is not present in Tru64 (osf).

The include sub-directory was introduced in version 1.25 and contains C header files. These header files are common to many utilities in this package. The header files are written to compile cleanly as C++ as well.

The lib sub-directory was introduced in version 1.25 and contains C source files that are used by many of the utilities. Depending on the target architecture and configure options, these files may be build into a library. The source files are written to compile cleanly as C or C++.

The src sub-directory was introduced in version 1.25 . It contains the C source code for each of the main utilities. In most cases each utility has a single C source file (e.g. sg_inq.c for the sg_inq utility). In some cases there may be an additional helper file (e.g. the sg_vpd utility has both sg_vpd.c and sg_vpd_vendor.c).

The scripts sub-directory contain shell scripts for common chores and for checking compliance. Unlike most utilities in the src sub-directory, many of these scripts can take multiple device names. For example: 'scsi_stop /dev/sd*' will attempt to stop (spin down) all SCSI disks. See the README file in that directory for more information.

Exit status

Each process containing one of sg3_utils' command line utilities completes with an exit status of 0 when successful. Prior to version 1.21 all errors yielded an exit status of 1. Having finer grain error reporting via the exit status from relatively low level sg3_utils utilities allows higher level scripts and other program wrappers to do more useful error processing.

From version 1.22 the exit status value is one of:

1 syntax error in command line options or their arguments, or an illegal combination of options.
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 a little while later.
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 operation code". This is often a supported command with a field set requesting an unsupported capability. For commands that require a "service action" field (e.g. READ CAPACITY(16) ) this value can indicate that the command 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 operation code" which means that the device doesn't support the requested command.
11 the device (or transport) reports an aborted command. In some cases this can be caused by congestion on the transport and retrying the command may be successful.
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". Some polling commands (e.g. REQUEST SENSE) can react this way. It is unlikely that this value will occur as an exit status.
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 the device has timed out. This occurs in Linux, in other ports a command timeout will appear as a transport (or OS) error.
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.

Many of the above exit statuses will be repeatable so executing the utility again with one or more '-v' options may yield more information. Unit attentions (exit status 6) are only reported once per condition. Notice that some of the lower exit status values correspond to the SCSI sense key values. For examples of bash scripts that use these exit values see the script files in the scripts sub-directory.

Changing mode page settings

SCSI devices store settings (metadata) that may possibly be changed by the user program (called the "application client" in SCSI jargon) in mode pages. It is a common requirement to find mode page settings and in some cases change them. An example is the Writeback Cache Enable (WCE) bit in the Caching mode page of SCSI disks. Usually the manufacturer's default setting for WCE is set (on) however in some RAID configurations it may be cleared (off).

Generic command line tools to change mode page settings tend to be difficult to use (which in some small part is due to the SCSI rules for manipulating mode pages). Here is a list of some linux utilities for changing mode pages:

scsiinfo (old utility): awkward command line interface that requires a double invocation (first to get, second to set). Only mode page fields that the utility knows about can be changed.
sginfo (sg3_utils version of scsiinfo): same awkward interface as scsiinfo but the mode pages are more up to date. Supports other modern features such as mode subpages.
sg_wr_mode (sg3_utils): low level mode page settings based on ASCII hex representation. Used with sg_modes to get a mode page in raw form and assumes ACSII hex will be edited. Low level but general.
sdparm (sdparm): uses acronyms (e.g. WCE) or numeric addressing to fetch and/or change mode page settings. Permits mode pages to be reset to their default settings. The user can choose whether changes are also made to the "saved" mode page values. The numeric addressing allows arbitrary fields to be changed (i.e. sdparm doesn't need to know about a mode page or its field structure in advance).
sgmode (scsirastools): interactive utility for setting mode pages with data held in preset ".mdf" files. Useful to setting a large number of disks to preset mode page values but awkward for manipulating a specific mode page field.
hdparm (hdparm): abstracts over ATA (mainly) and SCSI (where convenient) disks. Write caching can be turned on and off but that is one of the few mode page fields that can be changed on a SCSI device.
blktool (blktool): a newer and cleaner version of hdparm which targets the linux kernel 2.6 series. For SCSI devices only a relatively small (but important) number of mode page fields can be changed.
vendor specific (e.g. seatools from Seagate): several vendors have utilities like this. Worth investigating and often useful with disks from other manufacturers. Vendor extensions can be controlled (e.g. Seagate's desktop/server mode (also see sdparm's man page about this particular feature)).

The author's recommendation is to use sdparm unless the features of another utility better suit your needs.

Examples

The fundamental SCSI command whose support is mandatory for all SCSI devices is INQUIRY. All devices should respond to a "standard" (i.e. when no Vital Product Pages are requested) INQUIRY.

$ sg_inq /dev/sda
standard INQUIRY:
PQual=0 Device_type=0 RMB=0 version=0x03 [SPC]
[AERC=0] [TrmTsk=0] NormACA=0 HiSUP=1 Resp_data_format=2
SCCS=0 ACC=0 TGPS=0 3PC=0 Protect=0
BQue=0 EncServ=0 MultiP=0 MChngr=0 [ACKREQQ=0] Addr16=1
[RelAdr=0] WBus16=1 Sync=1 Linked=1 [TranDis=1] CmdQue=1
Clocking=0x3 QAS=0 IUS=0
    length=144 (0x90)   Peripheral device type: disk
Vendor identification: SEAGATE
Product identification: ST318451LW
Product revision level: 0003
Unit serial number: xxxxxxxxx

Some SCSI devices have version descriptor information showing which standards (and drafts) they support:

$ sg_inq -d /dev/sdb
standard INQUIRY:
PQual=0 Device_type=0 RMB=0 version=0x03 [SPC]
[AERC=0] [TrmTsk=0] NormACA=0 HiSUP=0 Resp_data_format=2
SCCS=0 ACC=0 TGPS=0 3PC=0 Protect=0
BQue=0 EncServ=0 MultiP=0 MChngr=0 [ACKREQQ=0] Addr16=1
[RelAdr=0] WBus16=1 Sync=1 Linked=1 [TranDis=1] CmdQue=1
Clocking=0x0 QAS=0 IUS=0
    length=96 (0x60)   Peripheral device type: disk
Vendor identification: FUJITSU
Product identification: MAM3184MP
Product revision level: 0106
Unit serial number: xxxxxxxxx

Version descriptors:
    SAM-2 (no version claimed)
    SPI-3 T10/1302-D revision 10
    SPC ANSI X3.301:1997
    SBC T10/0996-D revision 08c

Many modern SCSI devices also support "Vital Product Data" (VPD) pages. Here is a request to list available VPD pages:

$ sg_inq -e /dev/sg1
VPD INQUIRY, page code=0x00:
   [PQual=0 Peripheral device type: disk]
   Supported VPD pages:
     0x0        Supported VPD pages
     0x80       Unit serial number
     0x83       Device identification

For displaying VPD pages, sg_vpd (or sdparm) may be a better choice than sg_inq as sg_vpd has a simpler, less cluttered command line interface and additional support for vendor specific VPD pages.

# sg_vpd /dev/sdh
Supported VPD pages VPD page:
Supported VPD pages [sv]
Unit serial number [sn]
Implemented operating definition (obs) [iod]
Device identification [di]

The following displays a subset of the device identification VPD page, namely the designators for the target port:

# sg_vpd --page=di_port /dev/sdh
Device Identification VPD page:
Target port:
    designator type: Relative target port, code_set: Binary
     transport: Serial Attached SCSI (SAS)
      Relative target port: 0x1
    designator type: NAA, code_set: Binary
     transport: Serial Attached SCSI (SAS)
      0x5222222000000f9e

The sg_scan and sg_map utilities show the relationships between linux sg devices, their <bus, channel, target, lun> tuples and their primary device node names:

Example: given these 3 SCSI devices:
$ cat /proc/scsi/scsi
Attached devices:
Host: scsi1 Channel: 00 Id: 00 Lun: 00
Vendor: SEAGATE Model: ST318451LW       Rev: 0003
Type:   Direct-Access                    ANSI SCSI revision: 03
Host: scsi2 Channel: 00 Id: 04 Lun: 00
Vendor: PIONEER Model: DVD-ROM DVD-303 Rev: 1.10
Type:   CD-ROM                           ANSI SCSI revision: 02
Host: scsi2 Channel: 00 Id: 06 Lun: 00
Vendor: YAMAHA   Model: CRW4416S         Rev: 1.0g
Type:   CD-ROM                           ANSI SCSI revision: 02

then the output from sg_scan is:
$ sg_scan
/dev/sg0: scsi1 channel=0 id=0 lun=0 type=0 /dev/sg1: scsi2 channel=0 id=4 lun=0 type=5
/dev/sg2: scsi2 channel=0 id=6 lun=0 type=5

INQUIRY data can be added to that output with the '-i' option. The sg_map utility shows the mapping between scsi generic (sg) devices and the corresponding primary device node. For some peripheral device types, SCSI enclosures for example, there is no mapping and the enclosure device must be accessed via a sg device node.

$ sg_map /dev/sg0 /dev/sda /dev/sg1 /dev/scd0 /dev/sg2 /dev/scd1

In the lk 2.6 series of kernels sg_scan and sg_map are less important as most utilities in the sg3_utils package can be issued directly against the primary device node (e.g. /dev/sda). However the sg driver is still needed to "talk" to devices such as enclosures which have no specialized driver in linux.

Some examples of the use of the sg_persist utility can be found in the source tarball in examples/sg_persist_tst.sh . Some more information about that utility can be found in examples/transport_ids.txt .

The Windows port has its own sg_scan utility which attempts to list the common storage devices, one per line. Volume names corresponding to a storage device (or a partition on that device) are shown in brackets. Here are two examples, the second one adds a bus type field:

$ sg_scan
PD0     [C]     FUJITSU   MHY2160BH         0000
PD1     [DF]    WD        2500BEV External 1.05 WD-WXE90
CDROM0 [E]     MATSHITA DVD/CDRW UJDA775 CB03

$ sg_scan -b
PD0     [C]     <Ata > FUJITSU   MHY2160BH         0000
PD1     [DF]    <Usb > WD        2500BEV External 1.05 WD-WXE90
CDROM0 [E]     <Atapi> MATSHITA DVD/CDRW UJDA775 CB03

The PDO device name is a shortened form of PhysicalDrive0 and corresponds to volume C: . The USB connected PD1 contains two partitions recognised by Windows and they are D: and F: . Apart from the storage device names PD<n> and CDROM<n>, there is TAPE<n> for tape drives.

Notes

Starting with sg3_utils-1.09 a library called libsgutils is built in some environments and is required by most utilities. The library is made up of three source files: sg_lib.c, sg_cmds_basic.c and sg_cmds_extra.c plus their associated header files . The sg_lib.c file contains tables of SCSI command names, sense key and additional sense code strings and various related helper functions. The sg_cmds_basic.c file contains low level wrapper functions for commonly used SCSI commands. The sg_cmds_extra.c file contains low level wrapper functions for less commonly used SCSI commands. The library can be built both as a shared object and a static library. In version 1.25 the header files were placed in the include/ sub-directory and the library source files were placed in the lib/ sub-directory. The binary rpm package only contains the shared library while the sg3_utils-devel rpm package contains the static library, sg_lib.h, sg_cmds.h, sg_cmds_basic.h, sg_cmds_extra.h and some header files associated with the generic SCSI pass through interface. If users do not want libraries (shared or static) then refer to the INSTALL file in the main directory.

In Linux many of the utilities in the sg3_utils package ultimately use the SG_IO ioctl (rather than the older write()/read() interface) in the sg driver. In the lk 2.6 series the SG_IO ioctl (or at least a stripped down version of it) has been implemented in the block subsystem (see sg_io.html for more information). This means that commands which previously only worked on sg device names will now work on block device names as well (e.g. "sg_inq /dev/sda"). To use this facility safely version sg3_utils-1.02 or later should be used. Note that SCSI tape devices (both st and osst device drivers) are char devices and support the SG_IO ioctl from lk 2.6.6 onwards.

Download and build

Several recent versions of the sg3_utils package are listed below. The tarballs contain README, CHANGELOG (renamed "ChangeLog" in version 1.25), INSTALL, COVERAGE and CREDITS files plus man pages as well as source and build files. Here is the most recently released sg3_utils ChangeLog .

**Table 2. sg3_utils tarballs and packages**
sg3_utils version release date	tarballs	rpm source rpms **	i386 rpm binaries **	debian packages
1.20 20060418	sg3_utils-1.20.tgz	sg3_utils-1.20-1.src.rpm	sg3_utils-1.20-1.i386.rpm libsgutils-1_0-1.20-1.i386.rpm	sg3-utils_1.20-0.1_i386.deb libsgutils1-0_1.20-0.1_i386.deb
1.21 20060706	sg3_utils-1.21.tgz	sg3_utils-1.21-1.src.rpm	sg3_utils-1.21-1.i386.rpm libsgutils-1_0-1.21-1.i386.rpm	sg3-utils_1.21-0.1_i386.deb libsgutils1-0_1.21-0.1_i386.deb
1.22 20061016	sg3_utils-1.22.tgz	sg3_utils-1.22-1.src.rpm	sg3_utils-1.22-1.i386.rpm libsgutils-1_0-1.22-1.i386.rpm	sg3-utils_1.22-0.1_i386.deb libsgutils1-0_1.22-0.1_i386.deb
1.23 20070131	sg3_utils-1.23.tgz sg3_utils-1.23exe.zip	sg3_utils-1.23-1.src.rpm	sg3_utils-1.23-1.i386.rpm sg3_utils-libs-1.23-1.i386.rpm	sg3-utils_1.23-0.1_i386.deb libsgutils1_1.23-0.1_i386.deb
1.24 20070507	sg3_utils-1.24.tgz sg3_utils-1.24exe.zip	sg3_utils-1.24-1.src.rpm	sg3_utils-1.24-1.i386.rpm sg3_utils-libs-1.24-1.i386.rpm	sg3-utils_1.24-0.1_i386.deb libsgutils1_1.24-0.1_i386.deb
1.25 20071016	sg3_utils-1.25.tgz sg3_utils-1.25exe.zip	sg3_utils-1.25-1.src.rpm	sg3_utils-1.25-1.i386.rpm sg3_utils-libs-1.25-1.i386.rpm	sg3-utils_1.25-0.1_i386.deb libsgutils1_1.25-0.1_i386.deb
1.26 20080625	sg3_utils-1.26.tgz sg3_utils-1.26exe.zip	sg3_utils-1.26-1.src.rpm	sg3_utils-1.26-1.i386.rpm sg3_utils-libs-1.26-1.i386.rpm	sg3-utils_1.26-0.1_i386.deb libsgutils2_1.26-0.1_i386.deb
1.27 20090406	sg3_utils-1.27.tgz sg3_utils-1.27exe.zip	sg3_utils-1.27-1.src.rpm	sg3_utils-1.27-1.i386.rpm sg3_utils-libs-1.27-1.i386.rpm	sg3-utils_1.27-0.1_i386.deb libsgutils2_1.27-0.1_i386.deb
1.28 20091002	sg3_utils-1.28.tgz sg3_utils-1.28exe.zip	sg3_utils-1.28-1.src.rpm	sg3_utils-1.28-1.i386.rpm sg3_utils-libs-1.28-1.i386.rpm	sg3-utils_1.28-0.1_i386.deb libsgutils2-2_1.28-0.1_i386.deb

The sg3_utils-1.28exe.zip file is a zip archive of Windows executables made in a MinGW environment. This sg3_utils_man_html.tgz file is a tarball of man pages converted to html by man2html.

Version 1.14 of sg3_utils introduced a shared object (library) called libsgutils<num>. When binary packages are built then libsgutils<num> is in its own package (and there is another "libsgutils*-dev" package which contains C header files and a static libsgutils<num>.o library). The sg3_utils binaries for version 1.14 to 1.25 normally require the libsgutils<num> library but can be built without it. In the future other utilities such as sdparm may also depend on the libsgutils<num> package.

** Some browsers (e.g. firefox) may interpret a file with an extension of "rpm" as an audio file. In which case press the right button over the link and select "Save link as ..." to download the file.

Below is the most recent version of the sg_utils package which targets the linux kernel 2.2 series with some support for the lk 2.0 series. No further work is being done on this package.

**Table 3. sg_utils tarballs and packages**
sg_utils version	tarballs	rpm source rpms **	i386 rpm binaries **
1.02	sg_utils-1.02.tgz	sg_utils-1.02-1.src.rpm	sg_utils-1.02-1.i386.rpm

Version 1.25 of sg3_utils adds an autotools based "./configure ; make ; make install" build system. This replaced the previously hand-crafted Makefiles that were getting a bit hard to maintain, especially in ported (i.e. non-linux) environments. The configure.ac and Makefile.am files drive the autotools build. If the user decides to change either of these files, she should run the ./autogen.sh script. The autotools based logic only builds the source code found in the src sub-directory. Subdirectories such as utils and examples still have hand-craftded Makefiles.

Both sg3_utils and the older sg_utils packages can be found on http://freshmeat.net . Most of the above invocations can take the name of a specific utility (e.g. "make sg_inq") to build only that utility. There are also "install", "uninstall" and "clean" targets in most Makefiles.

Return to main page.

Last updated: 2nd October 2009