man pages section 1M: System Administration Commands

Exit Print View

Updated: July 2014

sg3_utils (1m)


sg3_utils - a package of utilities for sending SCSI commands


sg_* [--help]  [--hex]  [--maxlen=LEN]  [--raw]  [--verbose]


SG3_UTILS                                            SG3_UTILS(8)

     sg3_utils - a package of utilities for sending SCSI commands

     sg_* [--help]  [--hex]  [--maxlen=LEN]  [--raw]  [--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  pro-
     vided by the host operating system.

     The  names  of  all utilities start with "sg" and most start
     with "sg_" often followed by the name, or  a  shortening  of
     the  name,  of  the SCSI command that they send. For example
     the "sg_verify" utility sends the  SCSI  VERIFY  command.  A
     mapping  between  SCSI  commands and the sg3_utils utilities
     that issue them is shown in the COVERAGE file.

     SCSI draft standards can be found  at  .
     The  standards  themselves  can  be  purchased from ANSI and
     other standards organizations.  A good overview  of  various
     SCSI  standards can be seen in
     with the SCSI command sets in the upper part of the diagram.
     SCSI  commands  in common with all device types can be found
     in SPC of which SPC-4 is the  latest  major  version.  Block
     device specific commands (e.g. as used by disks) are in SBC,
     those for tape drives in SSC and those for CD/DVD/BD  drives
     in MMC.

     It  is  becoming  more  common to control ATA disks with the
     SCSI command set.  This involves  the  translation  of  SCSI
     commands to their corresponding ATA equivalents (and that is
     an imperfect mapping in some cases). The  relevant  standard
     is  called  SCSI  to  ATA Translation (SAT and SAT-2 are now
     standards at INCITS(ANSI) and ISO  while  SAT-3  is  at  the
     draft  stage).  The logic to perform the command translation
     is often called a SAT Layer or SATL and  may  be  within  an
     operating  system,  in  host  bus  adapter firmware or in an
     external device (e.g. associated with a SAS  expander).  See for more information.

     There  is  some  support  for  SCSI tape devices but not for
     their basic commands. The reader is  referred  to  the  "mt"

     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

sg3_utils-1.32      Last change: January 2012                   1

SG3_UTILS                                            SG3_UTILS(8)

     the  short  form  and  a "=" in the longer form (e.g. in the
     sg_verify utility '-l 2a6h'  and  '--lba=2a6h'  are  equiva-
     lent).  Note that with getopt_long(), short form options can
     be elided, for example: '-all' is equivalent to '-a -l  -l'.
     The  DEVICE  argument  may appear after, between or prior to
     any options.

     The older utilities, such as sg_inq, had individual  command
     line  processing  code  typically based on a single "-" fol-
     lowed 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  utili-
     ties  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  back-
     ward  compatibility.   By  default these older utilities use
     their getopt_long() based interface.  That can be overridden
     by  defining  the SG3_UTILS_OLD_OPTS environment variable or
     using '-O' or '--old' as the first command line option.  The
     man pages of the older utilities documents the details.

     Several sg3_utils utilities are based on the Unix dd command
     (e.g. sg_dd) and permit copying data at the  level  of  SCSI
     READ and WRITE commands. sg_dd is tightly bound to Linux and
     hence is not ported to other OSes. A  more  generic  utility
     (than  sg_dd)  called ddpt in a package of the same name has
     been ported to other OSes.

     Normal  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  (e.g.  lk  2.6
     series)  it  is becoming more common for almost all disks 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"

sg3_utils-1.32      Last change: January 2012                   2

SG3_UTILS                                            SG3_UTILS(8)

     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.

     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 "Physi-
     calDrive<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  Win-
     dows  blocks  attempts  to  use  it  if  a  class driver has
     "claimed" the device. There are SCSI device types (e.g.  Au-
     tomation/Drive  interface  type) for which there is no class
     driver. At least two transports ("bus types" in Windows jar-
     gon): 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 pack-

     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  parti-
     tions on it. Disk partitions that are not recognised by Win-
     dows are not usually given a volume name. However Vista does
     show a volume name for a disk which has no partitions recog-
     nised by it and when selected invites the user to format  it
     (which may be rather unfriendly to other OSes).

sg3_utils-1.32      Last change: January 2012                   3

SG3_UTILS                                            SG3_UTILS(8)

     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 between class and
     pass-through names.

     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 fol-
     lowing "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  fol-
     lowing 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  direc-
     tory. Tape drives appear in the /dev/rmt directory.

sg3_utils-1.32      Last change: January 2012                   4

SG3_UTILS                                            SG3_UTILS(8)

     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.

     To aid scripts that call these utilities, the exit status is
     set to indicate success (0) or failure  (1  or  more).  Note
     that  some  of the lower values correspond to the SCSI sense
     key values. The exit status values are:

     0    success

     1    syntax error.  Either  illegal  command  line  options,
          options  with bad arguments or a combination of options
          that is not permitted.

     2    the DEVICE reports that it is not ready for the  opera-
          tion  requested.  The  device  may be in the process of
          becoming ready (e.g.  spinning up but not at speed)  so
          the utility may work after a wait.

     3    the  DEVICE  reports  a  medium or hardware error (or a
          blank check). For example an attempt  to  read  a  cor-
          rupted block on a disk will yield this value.

     5    the  DEVICE  reports an "illegal request" with an addi-
          tional sense code other than "invalid command operation
          code".  This  is often a supported command with a field
          set requesting an unsupported capability. For  commands
          that  require  a  "service action" field this value can
          indicate that the  command  with  that  service  action
          value is not supported.

     6    the  DEVICE  reports a "unit attention" condition. This
          usually  indicates  that  something  unrelated  to  the
          requested  command  has  occurred (e.g. a device reset)
          potentially before the current SCSI command  was  sent.
          The  requested  command  has  not  been executed by the
          device. Note that unit attention conditions are usually
          only reported once by a device.

     9    the  DEVICE  reports  an  illegal request with an addi-
          tional sense code of "invalid command  operation  code"
          which  means  that  it  doesn't  support  the requested

sg3_utils-1.32      Last change: January 2012                   5

SG3_UTILS                                            SG3_UTILS(8)


     11   the DEVICE reports an aborted command.  In  some  cases
          aborted  commands  can  be retried immediately (e.g. if
          the transport aborted the command due to congestion).

     15   the utility is unable to open, close or use  the  given
          DEVICE.   The  given  file  name  could be incorrect or
          there may  be  permission  problems.  Adding  the  '-v'
          option may give more information.

     20   the  DEVICE  reports  it  has a check condition but "no
          sense" and non-zero information in its additional sense
          codes.  Some  polling commands (e.g. REQUEST SENSE) can
          receive this response.

     21   the DEVICE reports a "recovered error".  The  requested
          command  was  successful.  Most  likely  a utility will
          report a recovered error to stderr and continue, proba-
          bly leaving the utility with an exit status of 0 .

     33   the command sent to DEVICE has timed out.

     97   the response to a SCSI command failed sanity checks.

     98   the  DEVICE  reports  it  has a check condition but the
          error doesn't fit into any of the above categories.

     99   any errors that can't be categorized into values  1  to
          98  may  yield  this value. This includes transport and
          operating system errors after the command has been sent
          to the device.

     Most  of the error conditions reported above will be repeat-
     able (an example of one that is not is "unit attention")  so
     the  utility  can be run again with the '-v' option (or sev-
     eral) 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 mes-

     Some options are used uniformally in most of  the  utilities
     in  this  package. Those options are listed below. Note that
     there are some exceptions.

sg3_utils-1.32      Last change: January 2012                   6

SG3_UTILS                                            SG3_UTILS(8)

     -h, -?, --help
          output the usage message then  exit.  In  a  few  older
          utilities  the '-h' option requests hexadecimal output.
          In these cases the '-?' option will  output  the  usage
          message then exit.

     -H, --hex
          for  SCSI  commands  that yield a non-trivial response,
          print out that response in ASCII hexadecimal.

     -m, --maxlen=LEN
          several important SCSI commands (e.g. INQUIRY and  MODE
          SENSE)  have  response  lengths  that vary depending on
          many factors, only some of which these  utilities  take
          into  account. The maximum response length is typically
          specified in the 'allocation length' field of the  cdb.
          In  the absence of this option, several utilities use a
          default allocation length (sometimes recommended in the
          SCSI  draft  standards)  or  a "double fetch" strategy.
          See sg_logs(8) for its description of a "double  fetch"
          strategy.  These  techniques  are  imperfect and in the
          presence of faulty  SCSI  targets  can  cause  problems
          (e.g.  some  USB  mass  storage  devices freeze if they
          receive an INQUIRY allocation length  other  than  36).
          Also  use  of  this  option disables any "double fetch"
          strategy that may have otherwise been used.

     -r, --raw
          for SCSI commands that yield  a  non-trivial  response,
          output  that response in binary to stdout. If any error
          messages or warning are produced they are usually  sent
          to  stderr. Some utilities that consume data to send to
          the device along with the SCSI command, use this option
          to  provide  that  data or indicate that it can be read
          from stdin.

     -v, --verbose
          increase the level of verbosity, (i.e.  debug  output).
          Can  be  used  multiple  times to further increase ver-
          bosity.  The  additional  output  is  usually  sent  to

     -V, --version
          print  the  version  string and then exit. Each utility
          has its own  version  number  and  date  of  last  code

     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 inconve-
     nient to enter in the  default  decimal  representation.  So

sg3_utils-1.32      Last change: January 2012                   7

SG3_UTILS                                            SG3_UTILS(8)

     various other representations are permitted.

     Multiplicative  suffixes  are accepted. They are one, two or
     three letter strings appended directly after the  number  to
     which they apply:

        c C         *1
        w W         *2
        b B         *512
        k K KiB     *1024
        KB          *1000
        m M MiB     *1048576
        MB          *1000000
        g G GiB     *(2^30)
        GB          *(10^9)
        t T TiB     *(2^40)
        TB          *(10^12)
        p P PiB     *(2^50)
        PB          *(10^15)

     An  example  is  "2k" for 2048. The large tera and peta suf-
     fixes are only available for numeric  arguments  that  might
     require 64 bits to represent internally.

     A suffix of the form "x<n>" multiplies the leading number by
     <n>. An example is "2x33" for "66". The leading number  can-
     not be "0" (zero) as that would be interpreted as a hexadec-
     imal number (see below).

     These multiplicative suffixes are compatible with  GNU's  dd
     command  (since  2002)  which  claims compliance with SI and
     with IEC 60027-2.

     Alternatively numerical arguments can be given in  hexadeci-
     mal.  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".

     There are several Bourne shell scripts in the 'scripts' sub-
     directory  that invoke compiled utilities (e.g. sg_readcap).
     The scripts start with 'scsi_' rather than 'sg_'.  One  pur-
     pose  of  these  scripts  is  to call the same utility (e.g.
     sg_readcap) on multiple disks. Most of  the  basic  compiled
     utilities only allow one device as an argument. Some distri-
     butions install these scripts in a visible  directory  (e.g.
     /usr/src/bin).  Some of these scripts have man page entries.
     See the README file in the 'scripts' subdirectory.

sg3_utils-1.32      Last change: January 2012                   8

SG3_UTILS                                            SG3_UTILS(8)

     There is some example C code plus examples of complex  invo-
     cations  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 Win-
     dows 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  .  The  device  naming
     used  by  this  package  on various operating system is dis-
     cussed in the page: .

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

     Report bugs to <dgilbert at interlog dot com>.

     Copyright (C) 1999-2012 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  MER-

     See   attributes(5)   for   descriptions  of  the  following

     |Availability   | system/storage/sg3_utils |
     |Stability      | Uncommitted              |
     sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)

sg3_utils-1.32      Last change: January 2012                   9

SG3_UTILS                                            SG3_UTILS(8)

     This  software  was   built   from   source   available   at    The  original
     community       source       was       downloaded       from

     Further  information about this software can be found on the
     open        source        community        website        at

sg3_utils-1.32      Last change: January 2012                  10