1SG_REQUESTS(8)                     SG3_UTILS                    SG_REQUESTS(8)
2
3
4

NAME

6       sg_requests - send one or more SCSI REQUEST SENSE commands
7

SYNOPSIS

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

DESCRIPTION

14       Send SCSI REQUEST SENSE command to DEVICE and output the parameter data
15       response which is expected to be in sense data format. Both  fixed  and
16       descriptor sense data formats are supported.
17
18       Multiple  REQUEST SENSE commands can be sent with the --num=NUM option.
19       This can be used for timing purposes or monitoring the progress indica‐
20       tion.
21

OPTIONS

23       Arguments to long options are mandatory for short options as well.
24
25       -d, --desc
26              sets  the  DESC  bit  in  the REQUEST SENSE SCSI cdb. The DEVICE
27              should return sense data in descriptor (rather than fixed)  for‐
28              mat.  This  will  only occur if the DEVICE recognizes descriptor
29              format (SPC-3 and later). If the device is pre SPC-3  then  set‐
30              ting  a bit in a reserved field may cause a check condition sta‐
31              tus with an illegal request sense key, but will most  likely  be
32              ignored.
33
34       -e, --error
35              when  used  once it changes the REQUEST SENSE opcode from 0x3 to
36              0xff which should be rejected by the DEVICE. There  is  a  small
37              chance  that the device vendor has implemented a vendor specific
38              command at that opcode (0xff).  When used twice the pass-through
39              call  to send the SCSI command is bypassed.  The idea here is to
40              measure the user space overhead of this package's library to set
41              up  and process the response of a SCSI command. This option will
42              be typically used with the --num=NUM and  --time  options  where
43              NUM is a large number (e.g. 1000000).
44
45       -h, --help
46              output the usage message then exit.
47
48       -H, --hex
49              output response in ASCII hexadecimal.
50
51       -m, --maxlen=LEN
52              where  LEN  is  the  (maximum)  response  length in bytes. It is
53              placed in the cdb's "allocation length" field. If not given  (or
54              LEN  is  zero) then 252 is used. The maximum value of LEN is 255
55              (but SPC-4 recommends 252).
56
57       -n, --num=NUM
58              perform NUM SCSI REQUEST SENSE commands,  stopping  when  either
59              NUM  is reached or an error occurs. The default value for NUM is
60              1 .
61
62       --number=NUM
63              same action as --num=NUM. Added for compatibility with sg_turs.
64
65       -p, --progress
66              show  progress  indication  (a  percentage)  if  available.   If
67              --num=NUM  is  given,  NUM  is  greater  than  1  and an initial
68              progress indication was detected then this utility waits 30 sec‐
69              onds  before  subsequent  checks.   Exits when NUM is reached or
70              there are no more progress indications.   Ignores  --hex,  --raw
71              and --time options. See NOTES section below.
72
73       -r, --raw
74              output response in binary (to stdout).
75
76       -s, --status
77              if  the  REQUEST  SENSE command finished without error (as indi‐
78              cated by its SCSI status) then the  contents  of  the  parameter
79              data  are  analysed  as  sense  data  and the exit status is set
80              accordingly. The default action (i.e. when this  option  is  not
81              given)  is  to ignore the contents of the parameter data for the
82              purposes of setting the exit status.  Some types of error set  a
83              sense  key  of "NO SENSE" with non-zero information in the addi‐
84              tional  sense  code  (e.g.  the  FAILURE  PREDICTION   THRESHOLD
85              EXCEEDED  group  of codes); this results in an exit status value
86              of 10. If the sense key is "NO SENSE" and both asc and ascq  are
87              zero then the exit status is set to 0 . See the sg3_utils(8) man
88              page for exit status values.
89
90       -t, --time
91              time the SCSI REQUEST SENSE command(s) and calculate the average
92              number of operations per second.
93
94       -v, --verbose
95              increase the level of verbosity, (i.e. debug output).  Addition‐
96              ally the response (if received) is output in ASCII-HEX. Use this
97              option multiple times for greater verbosity.
98
99       -V, --version
100              print the version string and then exit.
101

NOTES

103       In  SCSI 1 and 2 the REQUEST SENSE command was very important for error
104       and warning processing in SCSI. The autosense capability rendered  this
105       command almost superfluous.
106
107       However  recent  SCSI  drafts  (e.g.  SPC-4  rev  14  and SBC-3 rev 14)
108       increase the utility of the REQUEST SENSE  command.  Idle  and  standby
109       (low) power conditions can be detected with this command.
110
111       The REQUEST SENSE command is not marked as mandatory in SPC-3 (i.e. for
112       all SCSI devices) but is marked as mandatory in SBC-2 (i.e. for disks),
113       SSC-3 (i.e. for tapes) and MMC-4 (i.e. for CD/DVD/HD-DVD/BD drives).
114
115       The  progress  indication  is optionally part of the sense data. When a
116       prior command that takes a long time to complete  (and  typically  pre‐
117       cludes  other  media  access  commands) is still underway, the progress
118       indication can be used to determine how long before the device  returns
119       to its normal state.
120
121       The  SCSI  FORMAT  command  for disks used with the IMMED bit set is an
122       example of an operation that takes a significant  amount  of  time  and
123       precludes  other  media  access  during  that  time.  The IMMED bit set
124       instructs the FORMAT command  to  return  control  to  the  application
125       client once the format has commenced (see SBC-3). Several long duration
126       SCSI commands associated with tape drives also use the progress indica‐
127       tion (see SSC-3).
128
129       Early standards suggested that the SCSI TEST UNIT READY command be used
130       for polling the progress indication (see the  sg_turs  utility).  Since
131       SPC-3  the standards suggest that the SCSI REQUEST SENSE command should
132       be used instead.
133
134       The DEVICE is opened with a read-only  flag  (e.g.  in  Unix  with  the
135       O_RDONLY flag).
136

EXIT STATUS

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

AUTHORS

142       Written by Douglas Gilbert.
143

REPORTING BUGS

145       Report bugs to <dgilbert at interlog dot com>.
146
148       Copyright © 2004-2017 Douglas Gilbert
149       This software is distributed under a FreeBSD license. There is NO  war‐
150       ranty;  not  even  for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
151       POSE.
152

SEE ALSO

154       sg_turs (sg3_utils)
155
156
157
158sg3_utils-1.45                     July 2018                    SG_REQUESTS(8)
Impressum