1SG_REQUESTS(8) SG3_UTILS SG_REQUESTS(8)
2
6 sg_requests - send one or more SCSI REQUEST SENSE commands
7
9 sg_requests [--desc] [--error] [--help] [--hex] [--maxlen=LEN]
10 [--num=NUM] [--number=NUM] [--progress] [--raw] [--status] [--time]
11 [--verbose] [--version] DEVICE
12
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 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
23 Arguments to long options are mandatory for short options as well.
24 -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 -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 -h, --help
46 output the usage message then exit.
47 -H, --hex
49 output response in ASCII hexadecimal.
50 -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 -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 --number=NUM
63 same action as --num=NUM. Added for compatibility with sg_turs.
64 -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 -r, --raw
74 output response in binary (to stdout).
75 -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 -t, --time
91 time the SCSI REQUEST SENSE command(s) and calculate the average
92 number of operations per second.
93 -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 -V, --version
100 print the version string and then exit.
101
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 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 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 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 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 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 The DEVICE is opened with a read-only flag (e.g. in Unix with the
135 O_RDONLY flag).
136
138 The exit status of sg_requests is 0 when it is successful. Otherwise
139 see the sg3_utils(8) man page.
140
142 Written by Douglas Gilbert.
143
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
154 sg_turs (sg3_utils)
155sg3_utils-1.45 July 2018 SG_REQUESTS(8)