Ubuntu Manpage: sg_read_buffer - send SCSI READ BUFFER command

Provided by: sg3-utils_1.48-2ubuntu1_amd64

NAME

       sg_read_buffer - send SCSI READ BUFFER command

SYNOPSIS

       sg_read_buffer   [--eh_code=EHC]  [--help]  [--hex]  [--id=ID]  [--inhex=FN]  [--length=LEN]  [--mode=MO]
       [--no_output] [--offset=OFF] [--raw] [--readonly] [--specific=MS] [--verbose] [--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.

       The  responses  to the Read microcode status ('rd_microc_st' [0xf]) and Error history ('err_hist' [0x1c])
       modes are decoded as described in spc6r06.pdf and earlier T10 documents.

       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.

-e, --eh_code=EHC
EHC is the error history code placed in the Buffer ID field of the cdb. The Mode field is set to
err_hist [0x1c]. The option is equivalent to using the '--mode=eh --id=EHC' options. If this
option and one of the other options is given, then an error will be generated if they contradict.
The default (maximum) response length is increased to 64 bytes when may need to be increased (if
so that is noted if the output is truncated).
An example is setting EHC to 0 in which case the error history directory will be decoded (unless
--hex or --raw options is given).

-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. When given three time the hex is
printed without addresses (indexes) at the start of each line; this type of format is suitable for
the --inhex=FN option on a subsequent invocation.

-i, --id=ID
this option sets the Buffer ID field in the cdb. ID is a value between 0 (default) and 255
inclusive. The meaning of the Buffer ID field varies with the value in the Mode field of the cdb.

-I, --inhex=FN
FN is expected to be a file name (or '-' for stdin) which contains 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, --id=ID and possible --specific=MS options, since these
are not present in the response. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils
manpage for more information. If the --raw option is also given then the contents of FN is treated
as binary.

-l, --length=LEN
where LEN is the length, in bytes, that is placed in the "allocation length" field in the cdb. The
default value is 4 (bytes) which is increased to 64 if the 'err_hist' mode [0x1c] is given or
implied. The device may respond with less bytes.
If the --inhex=FN option is given, then the default value of the length is increased to 8192
bytes. This length may then be reduced to match the number of bytes decoded from the contents of
FN.

-m, --mode=MO
this option sets the mode field in the cdb. MO is a value between 0 (default) and 31 inclusive.
Alternatively an abbreviation 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
descriptor give '--mode=desc' .

-N, --no_output
when this option is given after sending the SCSI command to the DEVICE the response is processed,
looking for any errors, and then this utility exits. Any data read by the READ BUFFER command is
ignored.
May be useful for timing larger reads from the DEVICE buffer in 'data' mode [0x2].

-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. When this option is given together
with --inhex=FN then the contents of FN is assumed to be binary and the output of this utility is
normal ASCII (i.e. _not_ in binary).

-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.  Following 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 (lowest) 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|eh  [28, 0x1c]
              Error history. Either 'err_hist' or the short  'eh'  abbreviation  can  be  used  for  this  mode.
              Introduced in SPC-4.

NOTES

       All numbers given with options are assumed to be decimal.  Alternatively numerical values can be given in
       hexadecimal preceded by either "0x" or "0X" (or has a trailing "h" or "H").

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 © 2006-2023 Luben Tuikov and Douglas Gilbert
       This  software  is  distributed  under  a  BSD-2-Clause  license.  There  is  NO  warranty;  not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.