sg3_utils(8) - phpMan

Command: man perldoc info search(apropos)  


SG3_UTILS(8)                                SG3_UTILS                                SG3_UTILS(8)

NAME
       sg3_utils - a package of utilities for sending SCSI commands

SYNOPSIS
       sg_*  [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--maxlen=LEN] [--raw] [--time-
       out=SECS] [--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 DE-
       VICE.

       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. The highest level (i.e. most abstract) document is the SCSI Ar-
       chitecture Model (SAM) with SAM-5 being the most recent standard  (ANSI  INCITS  515-2016)
       with  the  most recent draft being SAM-6 revision 4 . SCSI commands in common with all de-
       vice types can be found in SCSI Primary Commands (SPC) of which SPC-4 is the  most  recent
       standard (ANSI INCITS 513-2015). The most recent SPC draft is SPC-5 revision 19. Block de-
       vice specific commands (e.g. as used by disks) are in SBC, those for tape drives  in  SSC,
       those for SCSI enclosures in SES 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, SAT-2 and SAT-3) are now standards at INCITS(ANSI) and ISO while  SAT-4  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 operation. 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 func-
       tion, 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,  including  as  sg_inq,  sg_logs,  sg_modes,  sg_opcode,  sg_rbuff,
       sg_readcap, sg_senddiag, sg_start and sg_turs 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 ver-
       bosity).

       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 util-
       ities 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.  The getopt_long() is a GNU extension (i.e. not yet POSIX certified)  but
       more  recent command line utilities tend to use it. 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 copy-
       ing 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.

ENVIRONMENT VARIABLES
       The SG3_UTILS_OLD_OPTS environment variable is explained in the previous  section.  It  is
       only for backward compatibility of the command line options for older utilities.

       The  SG3_UTILS_DSENSE  environment  variable  may  be  set  to a number. If that number is
       non-zero then descriptor sense is set in the SNTL (the  small  SCSI  to  NVMe  Translation
       Layer within the underlying library).

       Several  utilities  have  their  own  environment  variable  setting (e.g.  sg_persist has
       SG_PERSIST_IN_RDONLY). See individual utility man pages for more information.

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 com-
       mon 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.  Addition-
       ally  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 tu-
       ple (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  Win-
       dows  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  up-
       per,  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 parti-
       tions 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 rec-
       ognized by it and when selected invites the user to format it (which  may  be  rather  un-
       friendly 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"  com-
       mand  may  be  useful for finding out which SCSI device names are available and the corre-
       spondence 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 num-
       ber (from the SCSI parallel interface days) and the number following "d" is the LUN.  Fol-
       lowing  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 ei-
       ther c5t4d3, c5t4d3s2 or c5t4d3p0 .

       And these device names are duplicated in the /dev/dsk and /dev/rdsk directories. The  for-
       mer  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'  com-
       mand"  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  direc-
       tory, only leaving what is "live". The "cfgadm -v" command looks promising.

NVME SUPPORT
       NVMe  (or NVM Express) is a relatively new storage transport and command set. The level of
       abstraction of the NVMe command set is somewhat lower the SCSI command sets, closer to the
       level of abstraction of ATA (and SATA) command sets. NVMe claims to be designed with flash
       and modern "solid state" storage in mind, something unheard of when  SCSI  was  originally
       developed in the 1980s.

       The SCSI command sets' advantage is the length of time they have been in place and the ex-
       isting tools (like these) to support it. Plus SCSI command sets level  of  abstraction  is
       both and advantage and disadvantage. Recently the NVME-MI (Management Interface) designers
       decide to use the SCSI Enclosure Services (SES-3) standard "as is" with  the  addition  of
       two  tunnelling NVME-MI commands: SES Send and SES Receive. This means after the OS inter-
       face differences are taken into account,  the  sg_ses,  sg_ses_microcode  and  sg_senddiag
       utilities can be used on a NVMe device that supports a newer version of NVME-MI.

       The  NVME-MI  SES Send and SES Receive commands correspond to the SCSI SEND DIAGNOSTIC and
       RECEIVE DIAGNOSTIC RESULTS commands respectively.  There are however a few other  commands
       that need to be translated, the most important of which is the SCSI INQUIRY command to the
       NVMe Identify controller/namespace. Version 1.43 of these utilities contain a  small  SNTL
       (SCSI to NVMe Translation Layer) to take care of these details.

       As a side effect of this "juggling" if the sg_inq utility is used (without the --page= op-
       tion) on a NVMe DEVICE then the actual NVMe Identifier (controller and possibly namespace)
       responses  are  decoded  and output. However if 'sg_inq --page=sinq <device>' is given for
       the same DEVICE then parts of the NVMe Identify  controller  and  namespace  response  are
       translated to a SCSI standard INQUIRY response which is then decoded and output.

       Apart  from  the  special  case with the sg_inq, all other utilities in the package assume
       they are talking to a SCSI device and decode any response accordingly. One  easy  way  for
       users  to see the underlying device is a NVMe device is the standard INQUIRY response Ven-
       dor Identification field of "NVMe    " (an 8 character long string with 4  spaces  to  the
       right).

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 listed below can be given to the sg_decode_sense utility (which is
       found in this package) as follows:
         sg_decode_sense --err=<exit_status>
       and a short explanatory string will be output to stdout.

       The exit status values are:

       0      success. Also used for some utilities that wish to return a boolean value  for  the
              "true"  case  (and  that no error has occurred). The false case is conveyed by exit
              status 36.

       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 ac-
              tion" 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 some-
              thing unrelated to the requested command has occurred (e.g. a device reset)  poten-
              tially 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  re-
              ported 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 re-
              tried 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.

       17     a  SCSI "Illegal request" sense code received with a flag indicating the Info field
              is valid. This is often a LBA but its meaning is command specific.

       18     the DEVICE reports a medium or hardware error (or a blank check) with a flag  indi-
              cating  the  Info field is valid. This is often a LBA (of the first encountered er-
              ror) but its meaning is command specific.

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

       22     the DEVICE reports that the current command or its parameters imply a logical block
              address (LBA) that is out of range. This happens surprisingly often when trying  to
              access  the last block on a storage device; either a classic "off by one" logic er-
              ror or a misreading of the response from READ CAPACITY(10 or 16) in which  the  ad-
              dress of the last block rather than the number of blocks on the DEVICE is returned.
              Since LBAs are origin zero they range from 0 to n-1 where n is the number of blocks
              on  the  DEVICE,  so the LBA of the last block is one less than the total number of
              blocks.

       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-6 defines this status as the  logi-
              cal  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  alle-
              giance" 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 an-
              other I_T nexus and the Control mode page TAS bit is set to one".

       31     error involving two or more command line options. They may be contradicting, select
              an unsupported mode, or a required option (given the context) is missing.

       32     there is a logic error in  the  utility.  It  corresponds  to  code  comments  like
              "shouldn't/can't get here". Perhaps the author should be informed.

       33     the command sent to DEVICE has timed out.

       36     no  error  has  occurred plus the utility wants to convey a boolean value of false.
              The corresponding true value is conveyed by a 0 exit status.

       40     the command sent to DEVICE has received an "aborted command" sense key with an  ad-
              ditional  sense code of 0x10. This group is related to problems with protection in-
              formation (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.

       41     the command sent to DEVICE has received an "aborted command" sense key with an  ad-
              ditional  sense  code  of 0x10 (as with error code) plus a flag indicating the Info
              field is valid.

       48     this is an internal message indicating a NVMe status field (SF) is other than  zero
              after  a  command has been executed (i.e. something went wrong).  Work in this area
              is currently experimental.

       49     low level driver reports a response's residual count (i.e. number of bytes actually
              received by HBA is 'requested_bytes - residual_count') that is

       50     OS  system  calls  that  fail  often return a small integer number to help. In Unix
              these are called "errno" values where 0 implies no error.  These  error  codes  set
              aside  51  to  96  for  mapping  these errno values but that may not be sufficient.
              Higher errno values that cannot be mapped are all mapped to this value (i.e. 50).
              Note that an errno value of 0 is mapped to error code 0.

       50 + <os_error_number>
              OS system calls that fail often return a small integer number to help indicate what
              the error is. For example in Unix the inability of a system call to allocate memory
              returns (in 'errno') ENOMEM which often is associated with the integer  12.  So  62
              (i.e.  '50  +  12')  may be returned by a utility in this case. It is also possible
              that a utility in this package reports 50+ENOMEM when it can't allocate memory, not
              necessarily  from  an  OS system call. In recent versions of Linux the file showing
              the mapping between symbolic constants (e.g. ENOMEM) and the corresponding  integer
              is in the kernel source code file: include/uapi/asm-generic/errno-base.h
              Note  that  errno  values  that are greater than or equal to 47 cannot fit in range
              provided. Instead they are all mapped to 50 as discussed in the previous entry.

       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.

       100-125
              these  error  codes  are used by the ddpt utility which uses the sg3_utils library.
              They are mainly specialized error codes associated with offloaded copies.

       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.

       -d, --dry-run
              utilities that can cause lots of user data to be lost or overwritten sometimes have
              a --dry-run option. Device modifying actions are typically bypassed (or skipped) to
              implement a policy of "do no harm".  This allows complex command  line  invocations
              to  be  tested  before  the  action required (e.g. format a disk) is performed. The
              --dry-run option has become a common feature of many command line  utilities  (e.g.
              the Unix 'patch' command), not just those from this package.
              Note  that  most  hyphenated option names in this package also can be given with an
              underscore rather than a hyphen (e.g.  --dry_run).

       -e, --enumerate
              some utilities (e.g. sg_ses and sg_vpd) store a lot of information in internal  ta-
              bles.  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  re-
              quests  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 buf-
              fer) 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 op-
              tion is also given in which case it is assumed to be binary. Notice that the  mean-
              ing  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 the 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. Alternatively 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).

       -t, --timeout=SECS
              utilities that issue potentially long-running SCSI commands often  have  a  --time-
              out=SECS  option.  This  typically instructs the operating system to abort the SCSI
              command in question once the timeout expires. Aborting SCSI commands is typically a
              messy  business  and  in the case of format like commands may leave the device in a
              "format corrupt" state requiring another long-running re-initialization command  to
              be sent. The argument, SECS, is usually in seconds and the short form of the option
              may be something other than -t since the timeout option was typically  added  later
              as storage devices grew in size and initialization commands took longer. Since many
              utilities had relatively long internal command timeouts before this option was  in-
              troduced,  the  actual command timeout given to the operating systems is the higher
              of the internal timeout and SECS.
              Many long running SCSI commands have an IMMED bit which causes the command to  fin-
              ish  relatively  quickly  but the initialization process to continue. In such cases
              the REQUEST SENSE command can be used to monitor progress with its progress indica-
              tion  field  (see the sg_requests and sg_turs utilities).  Utilities that send such
              SCSI command either have an --immed option or a --wait option which is the  logical
              inverse of the "immediate" action.

       -v, --verbose
              increase the level of verbosity, (i.e. debug output). Can be used multiple times to
              further increase verbosity. The additional output caused by this option  is  almost
              always 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  argu-
       ments can be large values (e.g. a logical block address (LBA) on a disk) and can be incon-
       venient 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 kB       *1000
          m M MiB     *1048576
          MB mB       *1000000
          g G GiB     *(2^30)
          GB 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  nu-
       meric 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  hexadeci-
       mal 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)  stan-
       dards.  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  mi-
       crocode 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 de-
       vices. 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' subdi-
       rectory. 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'  subdirec-
       tory.

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    .    There    is    a   git   code   mirror   at
       https://github.com/hreinecke/sg3_utils . The principle code repository uses subversion and
       is  on  the author's equipment. The author keeps track of this via the subversion revision
       number which is an ascending integer (currently at 774 for this package). The github  mir-
       ror  gets  updated periodically from the author's repository. Depending on the time of up-
       date, the above Downloads section at sg.danny.cz may be more up to date  than  the  github
       mirror.

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 (C) 1999-2018 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 utili-
       ties and thus contain the most reusable code, namely sg_lib.[hc],  sg_cmds_basic.[hc]  and
       sg_cmds_extra.[hc]  are  under  a FreeBSD license. There is NO warranty; not even for MER-
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

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

sg3_utils-1.44                            September 2018                             SG3_UTILS(8)

Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2024-05-14 12:00 @18.117.109.149 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
Valid XHTML 1.0!Valid CSS!