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, DVD and BD drives and
the media within them. SCSI command sets and transport definitions
can be found at the
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, 2.6, 3 and 4 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
further information about sg_utils.& This document describes version 1.42 of sg3_utils .& The majority
of these utilities have been ported to the FreeBSD, Solaris, Tru64
and the Windows operating systems (Windows 2000 and later
supported).
In the Linux kernel (lk) 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, 3
and 4 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)). From lk 2.6.28 bsg devices can also be used (e.g. /dev/bsg/3:0:0:0 ).
A list of SCSI and storage utility programs can be found on this
Contents of
This package contains over 50 utilities, their "man" pages, build
files and general documentation. 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 main utilities in the sg3_utils package:
Table 1. Main utilities
in sg3_utils
Utility name
Main SCSI commands
[legacy, use ]
MODE SENSE/SELECT, READ
[6, 10] [RD: 10, 12]
symbolic decoding (optional
changing) of mode pages. Can also output (disk) defect
lists. Port of older scsiinfo
READ, WRITE
[6, 10, 12, 16]
sg_dd variant that uses
memory mapped IO (only on Linux sg devices)
READ, WRITE
[6, 10, 12, 16]
sg_dd variant that uses POSIX
BACKGROUND CONTROL
start/stop advance background control
operations on disk
sg_compare_and_write
COMPARE AND WRITE
if compare successful then write
sg_copy_results
RECEIVE COPY RESULTS
used to get the results from the previous
sg_xcopy (EXTENDED COPY(LID1))
READ, WRITE
[6, 10, 12, 16]
Unix dd command variant, uses
SG_IO ioctl to send SCSI commands to copy data. See the sg_dd page. Newer ddpt utility adds features and is
ported to "f,s,w"
sg_decode_sense
decodes sense data given as a
string of hexadecimal bytes or in binary
sg_emc_trespass
MODE SELECT
utility specialized for EMC
Clariion series
FORMAT UNIT (SBC) and
FORMAT MEDIUM (SSC)
format or resize a SCSI disk
(with FORMAT UNIT). Alternatively sg_format can format a
tape (with FORMAT MEDIUM)
sg_get_config
GET CONFIGURATION
fetch features and profiles
of a cd/dvd drive and/or its current media
sg_get_lba_status
GET LBA STATUS
logical block provisioning
REPORT/SET IDENTIFYING
INFORMATION
default is to report (fetch)
the device identifier. With the '--set' option a new identifier is sent
to the device.
fetch standard response, VPD
pages or version descriptors. Also can perform IDENTIFY
(PACKET) DEVICE ATA command in Linux. If given an NVMe
device and no VPD page is requested or implied by the given
options then show NVMe Identify controller and namespace
responses. VPD page decoding also performed by sg_vpd and
fetch log sense pages, decode
standard and some vendor pages
REPORT LUNS
fetch luns reported by a
device (lun 0 or "well known lu")
shows mapping between sg
devices and primary device node (if any). Instead of using
sg_map, in lk 2.6 and later the lsscsi utility is
recommended.
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
and later. Instead of using sg_map26, the lsscsi
utility is recommended.
MODE SENSE
fetch mode pages (output
mainly in hex, to decode output use )
sg_opcodes
REPORT SUPPORTED OPERATION
fetch supported SCSI commands
or supported task management functions
sg_persist
PERSISTENT RESERVE IN/OUT
control persistent
reservations and report reservation status
sg_prevent
PREVENT ALLOW MEDIUM REMOVAL
control media removal, mainly
for those SCSI devices which have removable media (e.g.
CD/DVD and tape drives)
&user specified&
send user supplied cdb
READ BUFFER
read from SCSI device cache.
Typically for testing the SCSI transport (for throughput or
MODE SENSE/SELECT
display or modify RDAC
redundant controller mode page
[6, 10, 12, 16]
read continually from same
offset. Syntax similar to sg_dd (without write side). Can
test SCSI device cache and transport performance.
sg_read_attr
READ ATTRIBUTE
fetch and decode attributes. Modern tape
systems implement this SCSI command.
sg_readcap
READ CAPACITY
fetch the number of blocks
and the individual block size for disks and CD/DVD media
sg_read_buffer
READ BUFFER(10) and
READ BUFFER(16)
retrieve descriptors, error
history or data from device.
sg_read_long
read data from given LBA
which includes the block and ECC data.
sg_reassign
REASSIGN BLOCKS
reassign a LBA from one
sector on a disk (typically damaged) to a new (spare)
sector. User data copied if it is recoverable.
sg_referrals
REPORT REFERRALS
report data segment
accessibility from target port groups
sg_rep_zones
REPORT ZONES
sends this command to a ZBC (SMR) device and
decodes the result. A SAT layer may translate SCSI ZBC
commands to ATA ZAC commands that a disk understands
sg_requests
REQUEST SENSE
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.
Issue a driver, (SCSI) bus or
device (target or lun?) reset.
sg_reset_wp
RESET WRITE POINTER
sends this command to a ZBC (aka shared
magnetic recording [SMR]) device. The corresponding ATA
standard is known as ZAC.
READ MEDIA SERIAL NUMBER
Relatively new command added
to SPC-3. Format of response is vendor specific so this
utility outputs it in hex (default) or binary.
REPORT TARGET PORT GROUPS
Specialized for multi-ported
SCSI devices where one port (or a group of them) is
preferred for IO over another (or others).
READ BUFFER
fetch information from a
SAF-TE processor
sg_sanitize
Send SCSI SANITIZE command
sg_sat_identify
ATA PASS-THROUGH
Send ATA IDENTIFY DEVICE or
IDENTIFY PACKET DEVICE& commands via the SAT ATA
PASS-THROUGH SCSI command.
sg_sat_phy_event
ATA PASS-THROUGH
Sends an ATA READ LOG EXT
command via a SAT to fetch log page 11h which contains SATA
phy event counters.
sg_sat_read_gplog
ATA PASS-THROUGH
Sends an ATA READ LOG (DMA) EXT command via a
SAT to fetch a log page
sg_sat_set_features
ATA PASS_THROUGH
Sends ATA SET FEATURES
command via SAT
[.c.linux]
maps each sg device name to
the corresponding numeric &host, channel, target, lun&
tuple. In lk 2.6 series the "
-g" command is similar.
[.c.win32]
shows one device per line,
with the device's various names and INQUIRY response string
on that line.
sg_senddiag
SEND DIAGNOSTIC
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.
SEND/RECEIVE DIAGNOSTIC
Fetches status diagnostic
pages from, and sends some control pages to, a SCSI
Enclosure Services (SES) device. See the sg_ses page. Can pass-through to
NVMe enclosure if present.
sg_ses_microcode
SEND/RECEIVE DIAGNOSTIC
This microcode (firmware) download (to
device) is SES specific. A more general way, typically used
with disks, is with sg_write_buffer.
START STOP UNIT
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.
SET TARGET PORT GROUPS
Specialized for multi-ported
SCSI devices where one port (or a group of them) is
preferred for IO over another (or others).
SYNCHRONIZE CACHE
Causes disk caches to be
flushed to media
sg_test_rwbuf
READ/WRITE BUFFER
Random pattern written to
SCSI device buffer then read back and checked. Used in
testing for data corruption.
sg_timestamp
REPORT/SET TIMESTAMP
Report or set timestamp which is a 48 bit
unsigned integer containing the number of milliseconds since
00:00:00 UTC
TEST UNIT READY
Issue one or more Test Unit
Ready commands. Can be used to time SCSI command overhead.
logical block provisioning
support ("Trim" in the ATA world)
reads indicated blocks on a
SCSI disks, stops on the first error found. Does not yield
any data. Useful for media scans.
Decodes standard and some
vendor Vital Product Data (VPD) pages.
sg_write_buffer
WRITE BUFFER
can be used to
download firmware
sg_write_long
WRITE LONG
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
[10, 16, 32]
writes a single block to one
or more (consecutive) LBAs. Also supports some logical block
provisioning options.
sg_write_verify
WRITE AND VERIFY
send one or more commands to consecutive
LBAs, reading data from a given file or stdin.
sg_write_x
WRITE [16,32]
ORWRITE [16,32]
WRITE ATOMIC [16,32]
WRITE SAME [16,32]
WRITE SCATTERED [16,32]
WRITE STREAM [16, 32]
command line options will pick 1 of the 6
variants with 1 of the 2 cdb lengths. Almost all will
require the --in=IF option which identifies the file (IF)
holding the data (in binary) to be written. The exception is
--same=1 which sets the NDOB (no data-out buffer) flag in
the WRITE SAME command. Of the 32 byte cdb variants,
ORWRITE(32) is the only one that does not require the device
to be formatted with either type 1, 2 or 3 protection
information.
sg_wr_mode
MODE SELECT
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.
EXTENDED COPY(LID1)
Uses the EXTENDED COPY(LID1) command to copy
between disks. Note: the
utility contains this functionality and adds ODX (a subset
of XCOPY(LID4)) capability. ddpt is ported to f,s,w.
CLOSE ZONE, FINISH
ZONE, OPEN ZONE
Sends one of these commands to the given ZBC
device. See related sg_rep_zones and sg_reset_wp.
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 another peripheral device type. See the COVERAGE file
in the main directory for a more exhaustive list of SCSI (and ATA)
commands issued by the sg3_utils utilities.
The source code for all the main utilities in table 1 is found in
the src sub-directory.
Prior to version 1.25 this source was found in the main directory.
Each utility listed has a corresponding "man" page in the doc sub-directory. There is
also a 'man sg3_utils' page that documents conventions common to all
utilities in this package (e.g. their exit status values).
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")
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 and is documented in 'man sg3_utils'. Utilities with
this type of CLI are marked with "getopt" in the CLI column. The
earlier 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, README.freebsd,
README.solaris, README.tru64, README.win32, and the INSTALL files
for more information. Linux now has a sub-architecture of Android.
Below is a table of executable scripts (based on the bash shell,
other Unix shells may work) found in the scripts directory and
installed in some environments. In many cases these scripts use
executables listed in table 1. In several cases these scripts
overcome the restriction on the utilities in table 1 of only
accepting one device per invocation (e.g. scsi_readcap can report on
multiple devices while sg_readcap can only report on one). These
scripts have an "-h" option for help/usage and a '-v'
option for increased verbosity, amongst other options.
Table 2. Executable scripts in scripts directory
script name
Description
&&&&&&&&&&
rescan-scsi-bus.sh
copy of Kurt Garloff's useful script with
additions from Suse amongst others
scsi_logging_level
create, get or set Linux scsi logging level
scsi_mandat
check for mandatory SCSI command support
scsi_readcap
use SCSI READ CAPACITY command on each given
scsi_ready
use SCSI TEST UNIT READY on each given
check for SCSI to ATA Translation Layer
(SATL) support
scsi_start
use SCSI START STOP UNIT command to start
each &device&
use SCSI START STOP UNIT command to stop each
scsi_temperature
use SCSI LOG SENSE command to fetch
temperature of each &device&
Below is a table of other utilities (and scripts) found in sg3_utils
and related packages.
Table 3. Other utilities
in sg3_utils or related
Main SCSI commands
READ, WRITE
dd variant, rewrite of sg_dd. In its
own package:
converts stdin (assumed
binary) to ASCII hex and ASCII, sending its output to stdout
(like the Unix od
command and hexdump
sas_disk_blink
MODE SELECT
package. It blinks the ready LED on a SAS disk
scsi_inquiry
uses deprecated
SCSI_IOCTL_SEND_COMMAND ioctl
MODE SENSE/SELECT, INQUIRY
was in the sg3_utils package
now in own package, see
. sdparm manipulates mode pages, reads VPD pages and sends
simple commands
sg_chk_asc
check asc/ascq codes from www.t10.org page against
sg3_utils internal table
sg__sat_identify
ATA PASS-THROUGH
Simpler version of
sg_sat_identify that uses the Linux SG_IO ioctl directly.
sg__sat_phy_event
ATA PASS-THROUGH
Simpler version of
sg_sat_phy_event
sg__sat_set_features
ATA PASS_THROUGH
Simpler version of
sg_sat_set_features that uses the Linux SG_IO ioctl
sg_simple1,2,3,4,5
INQUIRY, TEST UNIT READY
Simple code examples of using
the scsi generic (sg) driver interface
sg_simple16
Simple code example of
sending a 16 byte cdb SCSI READ command
smp_discover
SAS SMP commands
discover phy attachments within a SAS
expander. In separate package:
The directory column
contains the name of the sub-directory in which the utility source
code is found. Source code in these sub-directories may, in some
cases, be built by Makefiles in those sub-directories. See the
README file for more information. Not all the code in the examples sub-directory is
listed in table 3. Some utilities in these sub-directories have
"man" pages.
This paragraph contains Linux specific information. All utilities
that issue SCSI commands and that appear in 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
table 1 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. 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 (i.e. configure.ac, Makefile.am, src/Makefile.am,
include/Makefile.am, lib/Makefile.am and doc/Makefile.am) 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. 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. There is a test script and data for the sg_persist utility. There
is also some test data for sg_reassign
and sg_senddiag
utilities.
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 in such a way so that they compile cleanly
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 suse sub-directory contains rules for building a Linux
Suse package (i.e. ".rpm") from the source code.
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
These command line utilities run as processes and finish 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.
Indicative exit status values were first added in version 1.22 , the
current list is shown below.
Table 4.& Exit status values
& Description
no error detected. Utility
completed successfully
syntax error in command line
options or their arguments, or an illegal combination of
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
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
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
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
the device reports& a& "data&
protect" sense key. This implies some mechanism has blocked
writes (or possibly all access to the media).
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
the device reports a "copy aborted" sense key
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
the device reports a "miscompare" sense key.
sg_verify and sg_compare_and_write may report this.
Introduced in version 1.37
the utility is unable to
open, close or use the given device or another file. The
given file name could be incorrect or there may be
permission problems. Adding the '-v' option may give more information
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
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
the device reports a SCSI status of
"reservation conflict". This implies that some other
initiator holds a reserv that
reservation may block writes or almost all access to that
device via the current initiator
the device reports a SCSI status of
"condition met". Currently only the PRE-FETCH command (see
SBC-4) yields this status.
the device reports a SCSI status of "busy".
SAM-5 defines this status as the logical unit is temporarily
unable to process a command.& It is recommended to
re-issue the command.
the device reports a SCSI status of "task set
the device reports a SCSI status of "ACA
active". ACA is "auto contingent allegiance" and is seldom
the device reports a SCSI status of "task
aborted". SAM-5 says: "This status shall be returned if a
command is aborted by a command or task management&
function on another I_T nexus and the Control mode page TAS
bit is set to one".
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
the command sent to device has received an
"aborted command" sense key with an additional sense code of
0x10. This is related to problems& with&
protection information (PI or DIF). Examples include reading
unmapped blocks or blocks that have never been written to
(since the last format)
An NVMe command terminated with a non-zero
status (status = ((SCT && 8) | SC) )
This is a Unix "errno" value (less than 45)
the response to a SCSI
command failed sanity checks
the device reports it has a
check condition but the error doesn't fit into any of the
above categories
any errors that can't be
categorized into values 1 to 98 may yield this value. This
includes transport and operating system errors
utility found but could not be executed.
Possibly a permissions problem or executable is for a
different architecture
utility not found
utility was interrupted by signal
utility tried to yield an exit status of 255
Many of the above exit status values 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 (e.g. 2 to 11)
correspond to the SCSI sense key values. Exit status 14 (miscompare)
was added in version 1.37 while 7, 10, 24 and 40 were added in
version 1.39 . Exit status values 0 plus 126 and above are
conventions for all Unix executables and scripts (i.e. they are not
sg3_utils specific). For examples of bash scripts that use these
exit values see the script files in the scripts sub-directory.
Changing mode page
SCSI devices store settings (meta-data) 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
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
unless the features of another utility better suit your needs.
Aside: device meta-data that cannot be changed by the user is often
placed in Vital Product Data (VPD) pages. The VPD pages can be
accessed via the SCSI INQUIRY command. The sg_vpd utility in this
package and
utility list the
contents of various VPD pages.
Most of these examples use Linux device names. See the device naming page for appropriate
device names in other supported operating systems.
Apart from the examples below, many of the utilities in this package
have an EXAMPLES section in their manpages. Also several utilities
have their own web page on this site (e.g. the sg_ses and
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&
LU_CONG=0& version=0x06& [SPC-4]
& [AERC=0]& [TrmTsk=0]& NormACA=0&
HiSUP=1& Resp_data_format=2
& SCCS=0& ACC=0& TPGS=0& 3PC=0&
Protect=1& [BQue=0]
& EncServ=0& MultiP=1 (VS=0)&
[MChngr=0]& [ACKREQQ=0]& Addr16=0
& [RelAdr=0]& WBus16=0& Sync=0&
[Linked=0]& [TranDis=0]& CmdQue=1
& [SPI: Clocking=0x0& QAS=0& IUS=0]
&&& length=144 (0x90)&& Peripheral
device type: disk
&Vendor identification: SEAGATE
&Product identification:
ST200FM0073&&&&
&Product revision level: CB02
&Unit serial number: xxxxxxx
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
ACC=0& TGPS=0& 3PC=0& Protect=0
EncServ=0& MultiP=0& MChngr=0& [ACKREQQ=0]&
& [RelAdr=0]&
WBus16=1& Sync=1& Linked=1& [TranDis=1]&
& Clocking=0x0&
QAS=0& IUS=0
&&& length=96
(0x60)&& Peripheral device type: disk
&Vendor identification:
&Product identification:
&Product revision level:
&Unit serial number:
& Version descriptors:
&&& SAM-2 (no
version claimed)
T10/1302-D revision 10
&&& SPC ANSI
X3.301:1997
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
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
& Unit serial number [sn]
& Implemented operating
definition (obs) [iod]
& Device identification
The following displays a subset of the device identification VPD
page, namely the designators for the target port:
# sg_vpd --page=di_port
Device Identification VPD
& 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)
&&&&& 0x0f9e
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
& Vendor: SEAGATE&
Model: ST318451LW&&&&&& Rev: 0003
Direct-Access&&&&&&&&&&&&&&&&&&&
ANSI SCSI revision: 03
Host: scsi2 Channel: 00 Id: 04
& Vendor: PIONEER&
Model: DVD-ROM DVD-303& Rev: 1.10
CD-ROM&&&&&&&&&&&&&&&&&&&&&&&&&&
ANSI SCSI revision: 02
Host: scsi2 Channel: 00 Id: 06
YAMAHA&& Model:
CRW4416S&&&&&&&& Rev:
CD-ROM&&&&&&&&&&&&&&&&&&&&&&&&&&
ANSI SCSI revision: 02
then the output from sg_scan is:
/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.
/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. Instead of
using sg_map, in lk 2.6 and later the lsscsi utility is
recommended.
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. On recent Windows
operating systems sg_scan needs to be run in a shell with
Administrator privileges. 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:
[C]&&&& FUJITSU&&
MHY2160BH&&&&&&&& 0000
WD&&&&&&& 2500BEV
External& 1.05& WD-WXE90
[E]&&&& MATSHITA DVD/CDRW UJDA775& CB03
$ sg_scan -b
[C]&&&& &Ata& &&
MHY2160BH&&&&&&&& 0000
[DF]&&& &Usb& &&
WD&&&&&&& 2500BEV
External& 1.05& WD-WXE90
[E]&&&& &Atapi&& MATSHITA DVD/CDRW
UJDA775& CB03
The PD0 device name is a shortened form of PhysicalDrive0 and
corresponds to volume C: . The USB connected PD1 contains two
partitions recognized 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.
libsgutils
The various utilities in this package were found to have a lot of
common code (e.g. use of the SCSI INQUIRY command and SCSI error
processing). So a library called libsgutils
has been created. Following Unix conventions the library is packaged
in two parts: the main part is needed at runtime by the utilities in
and a second "dev" package is required for any code
that wants to compile and built using this library. The "dev"
package contains the header files defining the libraries API amongst
other things.
The library API is relatively stable but is expanded and sometimes
changed in response to changes by
. The most recent Debian naming of this library was libsgutils2-2 .
Some other packages depend on this library.
Shared and static libraries are built by default. To build these
utilities so they don't depend on this shared library use './configure --disable-shared'.
Download and
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
Table 5. sg3_utils tarballs and packages
sg3_utils-1.20.tgz
sg3_utils-1.20-1.src.rpm
sg3_utils-1.20-1.i386.rpm
sg3-utils_1.20-0.1_i386.deb
sg3_utils-1.21.tgz
sg3_utils-1.21-1.src.rpm
sg3_utils-1.21-1.i386.rpm
sg3-utils_1.21-0.1_i386.deb
sg3_utils-1.23.tgz
sg3_utils-1.23-1.src.rpm
sg3_utils-1.23-1.i386.rpm
sg3-utils_1.23-0.1_i386.deb
sg3_utils-1.24.tgz
sg3_utils-1.24-1.src.rpm
sg3_utils-1.24-1.i386.rpm
sg3-utils_1.24-0.1_i386.deb
sg3_utils-1.25.tgz
sg3_utils-1.25-1.src.rpm
sg3_utils-1.25-1.i386.rpm
sg3-utils_1.25-0.1_i386.deb
sg3_utils-1.26.tgz
sg3_utils-1.26-1.src.rpm
sg3_utils-1.26-1.i386.rpm
sg3-utils_1.26-0.1_i386.deb
sg3_utils-1.27.tgz
sg3_utils-1.27-1.src.rpm
sg3_utils-1.27-1.i386.rpm
sg3-utils_1.27-0.1_i386.deb
sg3_utils-1.28.tgz
sg3_utils-1.28-1.src.rpm
sg3_utils-1.28-1.i386.rpm
sg3-utils_1.28-0.1_i386.deb
sg3_utils-1.29.tgz
sg3_utils-1.29-1.src.rpm
sg3_utils-1.29-1.i386.rpm
sg3-utils_1.29-0.1_i386.deb
sg3_utils-1.30.tgz
sg3_utils-1.30-1.src.rpm
sg3_utils-1.30-1.i386.rpm
sg3-utils_1.30-0.1_i386.deb
sg3_utils-1.31.tgz
sg3_utils-1.31-1.src.rpm
sg3_utils-1.31-1.i386.rpm
sg3-utils_1.31-0.1_i386.deb
sg3_utils-1.32.tgz
sg3_utils-1.32-1.src.rpm
sg3_utils-1.32-1.i386.rpm
sg3-utils_1.32-0.1_i386.deb
sg3_utils-1.33.tgz
sg3_utils-1.33-1.src.rpm
sg3_utils-1.33-1.i386.rpm
sg3-utils_1.33-0.1_i386.deb
see News section
on main page
file is a zip archive of Windows 32 bit executables made in a MinGW
environment. The
file is a zip archive of Windows 64 bit executables made with MinGW
tools. The
file is a tarball of man pages converted to html by man2html.
Version 1.25 of sg3_utils adds an autotools based './ 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 several Makefile.am
files guide the autotools build. If these files are changed then the
'./autogen.sh' script
should be run. The autotools based logic builds the code found in
the src, lib, include and doc sub-directories. The utils and examples sub-directories
still have hand-crafted Makefiles.
the ./configure
or& make steps
fail then it may be worth trying to run the './autogen.sh' script as
there are many versions of autotools and the mysterious libtool to
be found. Many options can be given to ./configure& and ./configure --help&
will list many of those options. By default& './configure ' will produce
Makefiles that install
under the /usr/local
directory (e.g. executables are placed in the /usr/local/bin directory).
To place executables in the more usual (at least for Linux) /usr/bin directory then use
'./configure --prefix=/
make install'.
* tarball also available
with a ".tar.gz" extension and bzipped with a ".tar.bz2" extension.
From version 1.31 the tarball is available with a ".xz" extension as
** Around the time of Fedora
11, RedHat changed their package checksums from MD5 to SHA256. The
above rpm packages are typically built with the most recent Fedora
at time of release. It has been reported that adding "--nomd5" to
the rpm command line may help with unpacking problems. See bug
490613 at RedHat's bugzilla.
*** 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 6.& sg_utils tarballs and packages
& tarballs&
rpm source rpms **
i386 rpm binaries **
sg_utils-1.02-1.src.rpm
sg_utils-1.02-1.i386.rpm
Git mirrors
The sg3_utils package is developed by the author using subversion.
Subversion revisions, which are ascending integers, can be seen in
the ChangeLog file. Many users have asked for git access and two
contributors have set up git mirrors on github:
Updates are sent to those mirrors whenever a beta is placed on the
main page, perhaps more often than that. Please report any problems
Last updated: 15th January 2018}