sg_read_buffer - send SCSI READ BUFFER command
sg_read_buffer [--help] [--hex] [--id=ID] [--inhex=FN] [--length=LEN] [--mode=MO] [--offset=OFF] [--raw] [--readonly] [--specific=MS] [--ver- bose] [--version] DEVICE
SG_READ_BUFFER(8) SG3_UTILS SG_READ_BUFFER(8)
NAME
sg_read_buffer - send SCSI READ BUFFER command
SYNOPSIS
sg_read_buffer [--help] [--hex] [--id=ID] [--inhex=FN] [--length=LEN]
[--mode=MO] [--offset=OFF] [--raw] [--readonly] [--specific=MS] [--ver-
bose] [--version] DEVICE
DESCRIPTION
Sends a SCSI READ BUFFER command to the DEVICE, and if there is a
response either decodes it, prints it in hexadecimal or sends it in
binary to stdout. If a response is received for a "descriptor" mode
then, in the absence of --hex and --raw, it is decoded. Response for
non-descriptor modes are output in hexadecimal unless the --raw option
is given.
This utility may be called without a DEVICE but with a --inhex=FN
option instead. FN is expected to be a file name (or '-' for stdin).
The contents of the file (or stdin stream) is assumed to be hexadecimal
(or binary) data that represents a SCSI READ BUFFER command response
and is decoded as such.
OPTIONS
Arguments to long options are mandatory for short options as well.
-h, --help
output the usage message then exit. If used multiple times also
prints the mode names and their acronyms.
-H, --hex
output the response in hexadecimal. When given twice the
response is output in hex with the corresponding representation
in ASCII to the right of each line.
-i, --id=ID
this option sets the buffer id field in the cdb. ID is a value
between 0 (default) and 255 inclusive.
-I, --inhex=FN
FN is expected to be a file name (or '-' for stdin) which con-
tains ASCII hexadecimal or binary representing a READ BUFFER
response. If known this utility will then decode that response.
It is preferable to also supply the --mode=MO and --specific=MS
options, since these are not present in the response. The hexa-
decimal should be arranged as 1 or 2 digits representing a byte
each of which is whitespace or comma separated. Anything from
and including a hash mark to the end of line is ignored. If the
--raw option is also given then FN is treated as binary.
-l, --length=LEN
where LEN is the length, in bytes, that is placed in the "allo-
cation length" field in the cdb. The default value is 4 (bytes).
The device may respond with less bytes.
-m, --mode=MO
this option sets the mode field in the cdb. MO is a value
between 0 (default) and 31 inclusive. Alternatively an abbrevia-
tion can be given. See the MODES section below. To list the
available mode abbreviations use an invalid one (e.g.
'--mode=xxx'). As an example, to fetch the read buffer descrip-
tor give '--mode=desc' .
-o, --offset=OFF
this option sets the buffer offset field in the cdb. OFF is a
value between 0 (default) and 2**24-1 . It is a byte offset.
-r, --raw
if a response is received then it is sent in binary to stdout.
-R, --readonly
open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read-write.
-S, --specific=MS
this option sets the mode specific field in the cdb. MS is a
value between 0 and 7 as this is a 3 bit field.
-v, --verbose
increase the level of verbosity, (i.e. debug output).
-V, --version
print the version string and then exit.
MODES
Following is a list of READ BUFFER command settings for the MODE field.
First is an acronym accepted by the MO argument of this utility. Fol-
lowing the acronym in square brackets are the corresponding decimal and
hex values that may also be given for MO. The following are listed in
numerical order.
hd [0, 0x0]
Combined header and data (obsolete in SPC-4).
vendor [1, 0x1]
Vendor specific.
data [2, 0x2]
Data.
desc [3, 0x3]
Descriptor: yields 4 bytes that contain an offset boundary field
(1 byte) and buffer capacity (3 bytes).
echo [10, 0xa]
Read data from echo buffer (was called "Echo buffer" in SPC-3).
echo_desc [11, 0xb]
Echo buffer descriptor: yields 4 bytes of which the last (low-
est) 13 bits represent the echo buffer capacity. The maximum
echo buffer size is 4096 bytes.
rd_microc_st [15, 0xf]
Read microcode status. Added in spc5r20 .
en_ex [26, 0x1a]
Enable expander communications protocol and Echo buffer. Made
obsolete in SPC-4.
err_hist [28, 0x1c]
Error history. Introduced in SPC-4.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Pass-through uncommitted |
+---------------+--------------------------+
NOTES
All numbers given with options are assumed to be decimal. Alterna-
tively numerical values can be given in hexadecimal preceded by either
"0x" or "0X" (or has a trailing "h" or "H").
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_read_buffer is 0 when it is successful. Otherwise
see the sg3_utils(8) man page.
AUTHORS
Written by Luben Tuikov and Douglas Gilbert.
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2006-2019 Luben Tuikov and 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_write_buffer(sg3_utils)
sg3_utils-1.45 May 2019 SG_READ_BUFFER(8)