Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019

sg3_utils (8)


sg3_utils - a package of utilities for sending SCSI commands


sg_*  [--enumerate]  [--help]  [--hex] [--in=FN] [--maxlen=LEN] [--raw]
[--verbose] [--version] [OTHER_OPTIONS] DEVICE


SG3_UTILS(8)                       SG3_UTILS                      SG3_UTILS(8)

       sg3_utils - a package of utilities for sending SCSI commands

       sg_*  [--enumerate]  [--help]  [--hex] [--in=FN] [--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 provided by the host
       operating system.

       The names of all utilities start with "sg" and most  start  with  "sg_"
       often  followed  by  the name, or a shortening of the name, of the SCSI
       command that they send. For example the "sg_verify" utility  sends  the
       SCSI  VERIFY command. A mapping between SCSI commands and the sg3_utils
       utilities that issue them is shown in the  COVERAGE  file.  The  sg_raw
       utility  can be used to send an arbitrary SCSI command (supplied on the
       command line) to the given DEVICE.

       sg_decode_sense can be used to decode SCSI sense data given on the com-
       mand line or in a file. sg_raw -vvv will output the T10 name of a given
       SCSI CDB which is most often 16 bytes or less in length.

       SCSI draft standards can be found at http://www.t10.org . The standards
       themselves  can  be  purchased  from ANSI and other standards organiza-
       tions.  A good overview of  various  SCSI  standards  can  be  seen  in
       http://www.t10.org/scsi-3.htm  with  the SCSI command sets in the upper
       part of the diagram. SCSI commands in common with all device types  can
       be  found  in  SPC  of  which  SPC-4 is the latest major version. Block
       device specific commands (e.g. as used by disks) are in SBC, those  for
       tape drives in SSC and those for CD/DVD/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  corre-
       sponding  ATA  equivalents  (and  that  is an imperfect mapping in some
       cases). The relevant standard is called SCSI to  ATA  Translation  (SAT
       and  SAT-2  are now standards at INCITS(ANSI) and ISO while SAT-3 is at
       the draft stage). The logic to perform the command translation is often
       called  a  SAT  Layer or SATL and may be within an operating system, in
       host bus adapter firmware or in an  external  device  (e.g.  associated
       with a SAS expander). See http://www.t10.org for more information.

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

       There are two generations of command line option usage. The newer util-
       ities (written since July 2004) use the getopt_long() function to parse
       command line options. With that function, each option has two represen-
       tations: a short form (e.g. '-v') and a longer form (e.g. '--verbose').
       If an argument is required then it follows a space (optionally) in  the
       short  form and a "=" in the longer form (e.g. in the sg_verify utility
       '-l  2a6h'  and  '--lba=2a6h'   are   equivalent).   Note   that   with
       getopt_long(), short form options can be elided, for example: '-all' is
       equivalent to '-a -l  -l'.   The  DEVICE  argument  may  appear  after,
       between or prior to any options.

       The  older  utilities, such as sg_inq, had individual command line pro-
       cessing code typically based on a single "-" followed by  one  or  more
       characters.  If  an  argument  is  needed  then  it follows a "=" (e.g.
       '-p=1f' in sg_modes with its older interface). Various options  can  be
       elided  as long as it is not ambiguous (e.g. '-vv' to increase the ver-

       Over time the command line interface of these  older  utilities  became
       messy  and  overloaded  with  options. So in sg3_utils version 1.23 the
       command line interface of these older utilities  was  altered  to  have
       both  a  cleaner  getopt_long() interface and their older interface for
       backward compatibility.  By default these  older  utilities  use  their
       getopt_long()  based interface.  That can be overridden by defining the
       SG3_UTILS_OLD_OPTS environment variable or using '-O' or '--old' as the
       first  command  line option. The man pages of the older utilities docu-
       ments 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 com-
       mands. 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.

       Most disk block devices have names like /dev/sda,  /dev/sdb,  /dev/sdc,
       etc.  SCSI disks in Linux have always had names like that but in recent
       Linux kernels it has become more common for many other disks (including
       SATA  disks  and USB storage devices) to be named like that. Partitions
       within a disk are specified by a number appended to  the  device  name,
       starting at 1 (e.g. /dev/sda1 ).

       Tape  drives are named /dev/st<num> or /dev/nst<num> where <num> starts
       at zero. Additionally one letter from this list: "lma" may be  appended
       to   the  name.  CD,  DVD  and  BD  readers  (and  writers)  are  named
       /dev/sr<num> where <num> start at zero. There are less used SCSI device
       type  names,  the dmesg and the lsscsi commands may help to find if any
       are attached to a running system.

       There is also a SCSI  device  driver  which  offers  alternate  generic
       access  to  SCSI  devices. It uses names of the form /dev/sg<num> where
       <num> starts at zero. The "lsscsi -g" command may be useful in  finding
       these  and  which  generic name corresponds to a device type name (e.g.
       /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI
       generic   driver   was  introduced  and  its  names  are  of  the  form
       /dev/bsg/<h:c:t:l> where h, c, t and l are numbers. Again see the  lss-
       csi  command  to  find the correspondence between that SCSI tuple (i.e.
       <h:c:t:l>) and alternate device names.

       Prior to the Linux kernel 2.6 series these  utilities  could  only  use
       generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux
       kernel 2.6 series, any device name can be used by these utilities.

       Very little has changed in Linux device naming in the  Linux  kernel  3
       and 4 series.

       Storage  and  related devices can have several device names in Windows.
       Probably the most common in the volume name (e.g. "D:"). There are also
       a  "class"  device  names  such  as  "PhysicalDrive<n>", "CDROM<n>" and
       "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order
       as devices are discovered (and sometimes rediscovered).

       Some  storage  devices have a SCSI lower level device name which starts
       with a SCSI (pseudo) adapter name of the form "SCSI<n>:".  To  this  is
       added  sub-addressing in the form of a "bus" number, a "target" identi-
       fier 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 can-
       not often be used directly since Windows blocks attempts to use it if a
       class  driver  has  "claimed"  the  device. There are SCSI device types
       (e.g.  Automation/Drive interface type) for which  there  is  no  class
       driver.  At  least  two transports ("bus types" in Windows jargon): USB
       and IEEE 1394 do not have a "scsi" device names of this form.

       In keeping with DOS file system conventions, the various  device  names
       can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
       tedious to write, a shortened form of "PD<n>" is permitted by all util-
       ities in this package.

       A  single device (e.g. a disk) can have many device names. For example:
       "PD0" can also be "C:", "D:" and "SCSI0:0,1,0". The  two  volume  names
       reflect  that  the  disk has two partitions on it. Disk partitions that
       are not recognized by Windows are not usually given a volume name. How-
       ever  Vista  does show a volume name for a disk which has no partitions
       recognized by it and when selected invites the user to format it (which
       may be rather unfriendly to other OSes).

       These  utilities  assume  a  given  device  name is in the Win32 device
       namespace.  To make that explicit "\\.\" can be prepended to the device
       names  mentioned  in  this  section. Beware that backslash is an escape
       character in Unix like shells and the  C  programming  language.  In  a
       shell like Msys (from MinGW) each backslash may need to be typed twice.

       The  sg_scan utility within this package lists out Windows device names
       in a form that is suitable for other utilities in this package to use.

       SCSI disks have block names of the form /dev/da<num> where <num> is  an
       integer  starting  at  zero. The "da" is replaced by "sa" for SCSI tape
       drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a  cor-
       responding  pass-through  device  name of the form /dev/pass<num> where
       <num> is an integer starting at zero. The "camcontrol devlist"  command
       may be useful for finding out which SCSI device names are available and
       the correspondence between class and pass-through names.

       SCSI device names below the /dev directory have a form  like:  c5t4d3s2
       where the number following "c" is the controller (HBA) number, the num-
       ber following "t" is the target number (from the SCSI  parallel  inter-
       face  days)  and the number following "d" is the LUN. Following the "s"
       is the slice number which is related to a partition and  by  convention
       "s2" is the whole disk.

       OpenSolaris also has a c5t4d3p2 form where the number following the "p"
       is the partition number apart from "p0" which is the whole disk.  So  a
       whole disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 .

       And  these  device  names  are duplicated in the /dev/dsk and /dev/rdsk
       directories. The former is the block device name and the latter is  for
       "raw"  (or  char  device)  access  which is what sg3_utils needs. So in
       OpenSolaris something of the form  'sg_inq  /dev/rdsk/c5t4d3p0'  should
       work.   If  it  doesn't  work  then  add a '-vvv' option for more debug
       information.  Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note  "rdsk"
       changed  to  "dsk")  will result in an "inappropriate ioctl for device"

       The device names within the /dev directory are typically symbolic links
       to  much  longer topological names in the /device directory. In Solaris
       cd/dvd/bd drives seem to be treated as disks and so are  found  in  the
       /dev/rdsk directory. Tape drives appear in the /dev/rmt directory.

       There  is  also  a sgen (SCSI generic) driver which by default does not
       attach to any device. See the  /kernel/drv/sgen.conf  file  to  control
       what  is  attached.  Any attached device will have a device name of the
       form /dev/scsi/c5t4d3 .

       Listing available SCSI devices in Solaris seems to be a challenge. "Use
       the  'format'  command"  advice works but seems a very dangerous way to
       list devices. [It does prompt again before doing any damage.] 'devfsadm
       -Cv'  cleans  out  the clutter in the /dev/rdsk directory, only leaving
       what is "live". The "cfgadm -v" command looks promising.

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

       0      success

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

       2      the DEVICE reports that  it  is  not  ready  for  the  operation
              requested.   The  DEVICE may be in the process of becoming ready
              (e.g.  spinning up but not at speed) so  the  utility  may  work
              after  a  wait.  In  Linux the DEVICE may be temporarily blocked
              while error recovery is taking place.

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

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

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

       7      the DEVICE reports a "data protect" sense key. This implies some
              mechanism  has  blocked  writes  (or  possibly all access to the

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

       10     the DEVICE reports a "copy aborted". This implies  another  com-
              mand  or  device  problem  has  stopped  a  copy  operation. The
              EXTENDED COPY family of commands (including WRITE  USING  TOKEN)
              may return this sense key.

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

       14     the  DEVICE  reports  a miscompare sense key. VERIFY and COMPARE
              AND WRITE commands may report this.

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

       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. There
              may be useful information in the sense data such as  a  progress

       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 .

       24     the DEVICE reports a SCSI status of "reservation conflict". This
              means  access  to  the  DEVICE with the current command has been
              blocked because another machine (HBA or SCSI "initiator")  holds
              a  reservation  on  this  DEVICE. On modern SCSI systems this is
              related to the use of the PERSISTENT RESERVATION family of  com-

       25     the  DEVICE  reports a SCSI status of "condition met". Currently
              only the PRE-FETCH command (see SBC-4) yields this status.

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

       27     the DEVICE reports a SCSI status of "task set full".

       28     the DEVICE reports a SCSI status of "ACA active". ACA  is  "auto
              contingent allegiance" and is seldom used.

       29     the  DEVICE reports a SCSI status of "task aborted". SAM-5 says:
              "This status shall be returned if a command is aborted by a com-
              mand  or  task  management function on another I_T nexus and the
              Control mode page TAS bit is set to one".

       33     the command sent to DEVICE has timed out.

       40     the command sent to DEVICE has  received  an  "aborted  command"
              sense  key  with an additional sense code of 0x10. This group is
              related to problems with protection information (PI or DIF). For
              example  this  error  may  occur when reading a block on a drive
              that has never been written (or is unmapped) if that  drive  was
              formatted with type 1, 2 or 3 protection.

       97     a SCSI command response 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.

       126    the utility was found but could  not  be  executed.  That  might
              occur if the executable does not have execute permissions.

       127    This  is the exit status for utility not found. That might occur
              when a script calls a utility in this package but the PATH envi-
              ronment  variable  has  not  been properly set up, so the script
              cannot find the executable.

       128 + <signum>
              If a signal kills a utility then the exit status is 128 plus the
              signal number. For example if a segmentation fault occurs then a
              utility is typically killed by SIGSEGV which according to 'man 7
              signal'  has an associated signal number of 11; so the exit sta-
              tus will be 139 .

       255    the utility tried to yield an exit status of 255 or larger. That
              should not happen; given here for completeness.

       Most  of  the  error  conditions  reported above will be repeatable (an
       example of one that is not is "unit attention") so the utility  can  be
       run again with the '-v' option (or several) to obtain more information.

       Arguments  to  long options are mandatory for short options as well. In
       the short form an argument to an option uses zero or more spaces  as  a
       separator (i.e. the short form does not use "=" as a separator).

       If  an option takes a numeric argument then that argument is assumed to
       be decimal unless otherwise indicated (e.g.  with  a  leading  "0x",  a
       trailing "h" or as noted in the usage message).

       Some  options are used uniformly in most of the utilities in this pack-
       age. Those options are listed below. Note that there  are  some  excep-

       -e, --enumerate
              some  utilities (e.g. sg_ses and sg_vpd) store a lot of informa-
              tion in internal tables. This option will output  that  informa-
              tion in some readable form (e.g. sorted by an acronym or by page
              number) then exit. Note that with this option DEVICE is  ignored
              (as  are  most other options) and no SCSI IO takes place, so the
              invoker does not need any elevated permissions.

       -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. To produce hexadecimal that
              can be parsed  by  other  utilities  (e.g.  without  a  relative
              address  to the left and without trailing ASCII) use this option
              three or four times.

       -i, --in=FN
              many SCSI commands fetch a significant amount of data  (returned
              in  the  data-in buffer) which several of these utilities decode
              (e.g. sg_vpd and sg_logs). To separate the two steps of fetching
              the  data  from  a SCSI device and then decoding it, this option
              has been added. The first step (fetching the data) can  be  done
              using the --hex or --raw option and redirecting the command line
              output to a file (often done with ">" in  Unix  based  operating
              systems).  The  difference  between  --hex and --raw is that the
              former produces output in ASCII hexadecimal while --raw produces
              its output in "raw" binary.
              The  second  step (i.e. decoding the SCSI response data now held
              in a file) can be done using this --in=FN option where the  file
              name  is  FN. If "-" is used for FN then stdin is assumed, again
              this allows for command line redirection (or piping). That  file
              (or  stdin)  is  assumed to contain ASCII hexadecimal unless the
              --raw option is also given in which case it  is  assumed  to  be
              binary. Notice that the meaning of the --raw option is "flipped"
              when used with --in=FN to act on the input, typically it acts on
              the output data.
              Since the structure of the data returned by SCSI commands varies
              considerably then the usage information or manpage of the  util-
              ity  being  used should be checked. In some cases --hex may need
              to be used multiple times (and is  more  conveniently  given  as
              '-HH'  or  '-HHH).  In  other  cases  the name of this option is

       -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 so as to not inter-
              fere with the output from this option.
              Some  utilities  that  consume  data to send to the DEVICE along
              with the SCSI command, use this option. Alernatively the --in=FN
              option  causes DEVICE to be ignored and the response data (to be
              decoded) fetched from a file  named  FN.  In  these  cases  this
              option  may  indicate that binary data can be read from stdin or
              from a nominated file (e.g. FN).

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

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

       Many  utilities  have command line options that take numeric arguments.
       These numeric arguments can be  large  values  (e.g.  a  logical  block
       address  (LBA)  on  a  disk)  and  can  be inconvenient to enter in the
       default decimal representation. So various  other  representations  are

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

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

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

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

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

       Alternatively  numerical  arguments  can be given in hexadecimal. There
       are two syntaxes. The number can be preceded by either "0x" or "0X"  as
       found in the C programming language. The second hexadecimal representa-
       tion 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 two standardized  methods  for  downloading  microcode  (i.e.
       device  firmware)  to  a  SCSI device. The more general way is with the
       SCSI WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclo-
       sures  have  their  own  method  based  on  the Download microcode con-
       trol/status diagnostic page, see the sg_ses_microcode utility.

       There are several bash shell scripts in the 'scripts' subdirectory that
       invoke  compiled  utilities  (e.g.  sg_readcap). Several of the scripts
       start with 'scsi_' rather than 'sg_'. One purpose of these  scripts  is
       to call the same utility (e.g. sg_readcap) on multiple devices. Most of
       the basic compiled utilities only allow one device as an argument. Some
       distributions  install  these scripts in a more visible directory (e.g.
       /usr/bin). Some of these scripts have man page entries. See the  README
       file in the 'scripts' subdirectory.

       There  is  some  example C code plus examples of complex invocations in
       the 'examples' subdirectory. There is also a README file. The example C
       may  be  a  simpler  example of how to use a SCSI pass-through in Linux
       than the main utilities (found in the 'src' subdirectory). This is  due
       to  the  fewer  abstraction  layers (e.g. they don't worry the MinGW in
       Windows may open a file in text rather than binary mode).

       Some utilities that the author has found useful have been placed in the
       'utils' subdirectory.

       There     is    a    web    page    discussing    this    package    at
       http://sg.danny.cz/sg/sg3_utils.html . The device naming used  by  this
       package    on    various    operating    systems   is   discussed   at:
       http://sg.danny.cz/sg/device_name.html .

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

       Report bugs to <dgilbert at interlog dot com>.

       Copyright (C) 1999-2016 Douglas Gilbert
       Some utilities are distributed under a GPL version 2 license while oth-
       ers, usually more recent ones, are under a FreeBSD license.  The  files
       that are common to almost all utilities and thus contain the most reus-
       able    code,    namely     sg_lib.[hc],     sg_cmds_basic.[hc]     and
       sg_cmds_extra.[hc]  are  under a FreeBSD license. There is NO warranty;

       See attributes(7) for descriptions of the following attributes:

       |Availability   | system/storage/sg3_utils |
       |Stability      | Pass-through uncommitted |
       sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)

       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://sg.danny.cz/sg/p/sg3_utils-1.42.tgz

       Further information about this software can be found on the open source
       community website at http://sg.danny.cz/sg/sg3_utils.html.

sg3_utils-1.42                   February 2016                    SG3_UTILS(8)