Provided by: sg3-utils_1.40-0ubuntu1_amd64 bug

NAME

       sg3_utils - a package of utilities for sending SCSI commands

SYNOPSIS

       sg_*  [--help]  [--hex]  [--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 lk 3 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.

       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.

       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.

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

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