Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

sg_read_buffer (8)


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)

       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

       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.

       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.

       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]

       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.

       See attributes(7) for descriptions of the following attributes:

       |Availability   | system/storage/sg3_utils |
       |Stability      | Pass-through uncommitted |

       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-

       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.

       The exit status of sg_read_buffer is 0 when it is successful. Otherwise
       see the sg3_utils(8) man page.

       Written by Luben Tuikov and Douglas Gilbert.

       Report bugs to <dgilbert at interlog dot com>.

       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-


sg3_utils-1.45                     May 2019                  SG_READ_BUFFER(8)