bionic (8) sg_requests.8.gz

NAME

       sg_requests - send one or more SCSI REQUEST SENSE commands

SYNOPSIS

       sg_requests [--desc] [--help] [--hex] [--maxlen=LEN] [--num=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 indication.

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) format. This will only occur if the DEVICE recognizes descriptor format (SPC-3
              and later). If the device is pre SPC-3 then setting a bit in a reserved field may  cause  a  check
              condition status with an illegal request sense key, but will most likely be ignored.

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

       -p, --progress
              show progress indication (a percentage) if available. If --number=NUM is  given,  NUM  is  greater
              than  1  and an initial progress indication was detected then this utility waits 30 seconds 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 indicated 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  additional  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).  Additionally 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.

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 precludes 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  indication  (see
       SSC-3).

       Early  standards  suggested  that  the  SCSI  TEST  UNIT  READY  command be used for polling the progress
       indication. More recent standards seem to suggest 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).

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 © 2004-2014 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO warranty; not even for  MERCHANTABILITY
       or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       sg3_utils