Man Linux: Main Page and Category List


       sg3_utils - a package of utilities for sending SCSI commands


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


       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.

       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/HD_DVD/BD drives in

       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" utility.

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

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

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


       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.

       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
              executed by the device. Note that unit attention conditions  are
              usually only reported once by a device.

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

       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

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

       -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   verbosity.   The
              additional 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
       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’ subdirectory
       that invoke compiled utilities (e.g.  sg_readcap).  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 disks. Most of the basic
       compiled   utilities  only  allow  one  device  as  an  argument.  Some
       distributions 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.

       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 .


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


       Report bugs to <dgilbert at interlog dot com>.


       Copyright © 1999-2010 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;


       sdparm(sdparm), ddpt(ddpt), mt(1)