Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

sg_requests (8)

Name

sg_requests - send one or more SCSI REQUEST SENSE commands

Synopsis

sg_requests   [--desc]   [--error]   [--help]   [--hex]  [--maxlen=LEN]
[--num=NUM] [--number=NUM]  [--progress]  [--raw]  [--status]  [--time]
[--verbose] [--version] DEVICE

Description

SG_REQUESTS(8)                     SG3_UTILS                    SG_REQUESTS(8)



NAME
       sg_requests - send one or more SCSI REQUEST SENSE commands

SYNOPSIS
       sg_requests   [--desc]   [--error]   [--help]   [--hex]  [--maxlen=LEN]
       [--num=NUM] [--number=NUM]  [--progress]  [--raw]  [--status]  [--time]
       [--verbose] [--version] DEVICE

DESCRIPTION
       Send SCSI REQUEST SENSE command to DEVICE and output the parameter data
       response which is expected to be in sense data format. Both  fixed  and
       descriptor sense data formats are supported.

       Multiple  REQUEST SENSE commands can be sent with the --num=NUM option.
       This can be used for timing purposes or monitoring the progress indica-
       tion.

OPTIONS
       Arguments to long options are mandatory for short options as well.

       -d, --desc
              sets  the  DESC  bit  in  the REQUEST SENSE SCSI cdb. The DEVICE
              should return sense data in descriptor (rather than fixed)  for-
              mat.  This  will  only occur if the DEVICE recognizes descriptor
              format (SPC-3 and later). If the device is pre SPC-3  then  set-
              ting  a bit in a reserved field may cause a check condition sta-
              tus with an illegal request sense key, but will most  likely  be
              ignored.

       -e, --error
              when  used  once it changes the REQUEST SENSE opcode from 0x3 to
              0xff which should be rejected by the DEVICE. There  is  a  small
              chance  that the device vendor has implemented a vendor specific
              command at that opcode (0xff).  When used twice the pass-through
              call  to send the SCSI command is bypassed.  The idea here is to
              measure the user space overhead of this package's library to set
              up  and process the response of a SCSI command. This option will
              be typically used with the --num=NUM and  --time  options  where
              NUM is a large number (e.g. 1000000).

       -h, --help
              output the usage message then exit.

       -H, --hex
              output response in ASCII hexadecimal.

       -m, --maxlen=LEN
              where  LEN  is  the  (maximum)  response  length in bytes. It is
              placed in the cdb's "allocation length" field. If not given  (or
              LEN  is  zero) then 252 is used. The maximum value of LEN is 255
              (but SPC-4 recommends 252).

       -n, --num=NUM
              perform NUM SCSI REQUEST SENSE commands,  stopping  when  either
              NUM  is reached or an error occurs. The default value for NUM is
              1 .

       --number=NUM
              same action as --num=NUM. Added for compatibility with sg_turs.

       -p, --progress
              show  progress  indication  (a  percentage)  if  available.   If
              --num=NUM  is  given,  NUM  is  greater  than  1  and an initial
              progress indication was detected then this utility waits 30 sec-
              onds  before  subsequent  checks.   Exits when NUM is reached or
              there are no more progress indications.   Ignores  --hex,  --raw
              and --time options. See NOTES section below.

       -r, --raw
              output response in binary (to stdout).

       -s, --status
              if  the  REQUEST  SENSE command finished without error (as indi-
              cated by its SCSI status) then the  contents  of  the  parameter
              data  are  analysed  as  sense  data  and the exit status is set
              accordingly. The default action (i.e. when this  option  is  not
              given)  is  to ignore the contents of the parameter data for the
              purposes of setting the exit status.  Some types of error set  a
              sense  key  of "NO SENSE" with non-zero information in the addi-
              tional  sense  code  (e.g.  the  FAILURE  PREDICTION   THRESHOLD
              EXCEEDED  group  of codes); this results in an exit status value
              of 10. If the sense key is "NO SENSE" and both asc and ascq  are
              zero then the exit status is set to 0 . See the sg3_utils(8) man
              page for exit status values.

       -t, --time
              time the SCSI REQUEST SENSE command(s) and calculate the average
              number of operations per second.

       -v, --verbose
              increase the level of verbosity, (i.e. debug output).  Addition-
              ally the response (if received) is output in ASCII-HEX. Use this
              option multiple times for greater verbosity.

       -V, --version
              print the version string and then exit.


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


       +---------------+--------------------------+
       |ATTRIBUTE TYPE |     ATTRIBUTE VALUE      |
       +---------------+--------------------------+
       |Availability   | system/storage/sg3_utils |
       +---------------+--------------------------+
       |Stability      | Pass-through uncommitted |
       +---------------+--------------------------+

NOTES
       In  SCSI 1 and 2 the REQUEST SENSE command was very important for error
       and warning processing in SCSI. The autosense capability rendered  this
       command almost superfluous.

       However  recent  SCSI  drafts  (e.g.  SPC-4  rev  14  and SBC-3 rev 14)
       increase the utility of the REQUEST SENSE  command.  Idle  and  standby
       (low) power conditions can be detected with this command.

       The REQUEST SENSE command is not marked as mandatory in SPC-3 (i.e. for
       all SCSI devices) but is marked as mandatory in SBC-2 (i.e. for disks),
       SSC-3 (i.e. for tapes) and MMC-4 (i.e. for CD/DVD/HD-DVD/BD drives).

       The  progress  indication  is optionally part of the sense data. When a
       prior command that takes a long time to complete  (and  typically  pre-
       cludes  other  media  access  commands) is still underway, the progress
       indication can be used to determine how long before the device  returns
       to its normal state.

       The  SCSI  FORMAT  command  for disks used with the IMMED bit set is an
       example of an operation that takes a significant  amount  of  time  and
       precludes  other  media  access  during  that  time.  The IMMED bit set
       instructs the FORMAT command  to  return  control  to  the  application
       client once the format has commenced (see SBC-3). Several long duration
       SCSI commands associated with tape drives also use the progress indica-
       tion (see SSC-3).

       Early standards suggested that the SCSI TEST UNIT READY command be used
       for polling the progress indication (see the  sg_turs  utility).  Since
       SPC-3  the standards suggest that the SCSI REQUEST SENSE command should
       be used instead.

       The DEVICE is opened with a read-only  flag  (e.g.  in  Unix  with  the
       O_RDONLY flag).

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

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

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

EXIT STATUS
       The exit status of sg_requests is 0 when it  is  successful.  Otherwise
       see the sg3_utils(8) man page.

AUTHORS
       Written by Douglas Gilbert.

REPORTING BUGS
       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT
       Copyright (C) 2004-2017 Douglas Gilbert
       This  software is distributed under a FreeBSD license. There is NO war-
       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR-
       POSE.

SEE ALSO
       sg_turs (sg3_utils)




sg3_utils-1.45                     July 2018                    SG_REQUESTS(8)