Provided by: sg3-utils_1.42-2ubuntu1.18.04.2_amd64 bug

NAME

       sg3_utils - a package of utilities for sending SCSI commands

SYNOPSIS

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

DESCRIPTION

       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 command 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 organizations.  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 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 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 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 verbosity).

       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.

LINUX DEVICE NAMING

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

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

WINDOWS DEVICE NAMING

       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"
       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 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
       utilities 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. However 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.

FREEBSD DEVICE NAMING

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

SOLARIS DEVICE NAMING

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

EXIT STATUS

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

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

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

       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 command 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 environment 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 status 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.

COMMON OPTIONS

       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 package. Those options are listed below.
       Note that there are some exceptions.

       -e, --enumerate
              some utilities (e.g. sg_ses and sg_vpd) store a lot of information in internal tables. This option
              will output that information 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 utility 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 --inhex=FN.

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

NUMERIC ARGUMENTS

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

MICROCODE AND FIRMWARE

       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 enclosures
       have their  own  method  based  on  the  Download  microcode  control/status  diagnostic  page,  see  the
       sg_ses_microcode utility.

SCRIPTS, EXAMPLES and UTILS

       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.

WEB SITE

       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
       .

AUTHORS

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

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 1999-2016 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 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)

sg3_utils-1.42                                    February 2016                                     SG3_UTILS(8)