sg_requests - send one or more SCSI REQUEST SENSE commands
sg_requests [--desc] [--error] [--help] [--hex] [--maxlen=LEN] [--num=NUM] [--number=NUM] [--progress] [--raw] [--status] [--time] [--verbose] [--version] DEVICE
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)