sg_read_attr - send SCSI READ ATTRIBUTE command

       Written by Douglas Gilbert.

       Copyright © 2016-2020 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.

       Sends  a SCSI READ ATTRIBUTE command to DEVICE and outputs the data returned. This command was introduced
       in SPC-3 revision 1 and thus is applicable to all SCSI devices. In practice it is used  mainly  for  tape
       systems. This utility is based on the SPC-5 draft standard, revision 17 (spc5r17.pdf).

       To list the attributes of a tape drive whose DEVICE is /dev/sg1 , the following could be used:

         # sg_read_attr -s al /dev/sg1
         Attribute list:
           Remaining capacity in partition [MiB]
           Maximum capacity in partition [MiB]
           TapeAlert flags
           Load count
           MAM space remaining [B]
           Assigning organization
           Format density code
           ...

       To check the number of partitions:

         # sg_read_attr -s pl /dev/sg1
         Partition number list:
           First partition number: 0
           Number of partitions available: 2

       And to see the attribute values (which is the default service action):

         # sg_read_attr /dev/sg1
         Attribute values:
           Remaining capacity in partition [MiB]: 1386103
           Maximum capacity in partition [MiB]: 1386103
           TapeAlert flags: 0
           ....

       To redirect the attribute values response to a file for later decoding:

         # sg_read_attr -HHH /dev/sg1 > av.hex

       And later the response held in the av.hex file could be decoded with:

         # sg_read_attr -s av --in=av.hex
         Attribute values:
           Remaining capacity in partition [MiB]: 1386103
           Maximum capacity in partition [MiB]: 1386103
           TapeAlert flags: 0
           ....

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

       sg_read_attr - send SCSI READ ATTRIBUTE command

       Only tape systems seem to implement the SCSI READ ATTRIBUTE command. The vast majority of its  definition
       is in the SPC standard so other device types could use it.

       Much  of the information provided by READ ATTRIBUTE can also be found in pages returned by LOG SENSE (see
       the sg_logs utility) and in the VPD pages returned by the INQUIRY command.

       Arguments to long options are mandatory for short options as well.

       -c, --cache
              sets  the  CACHE  bit in the READ ATTRIBUTE cdb. This instructs the device server to return cached
              attributes. By default that bit is cleared which instructs the device server not to return  cached
              attributes.

       -e, --enumerate
              enumerates  all  known  attributes  and service actions. Attributes include an identifier, length,
              format and a name as defined by T10. If DEVICE is given then it is ignored.

       -E, --ea=EA
              where EA is an element address which is placed in the READ ATTRIBUTE cdb. This field is only found
              in SMC-2 and SMC-3 drafts for medium changers usually associated with tape libraries.  By  default
              this field is set to zero.

       -f, --filter=FL
              where  FL  is  an  attribute  identifier in the range 0 to 65535 or -1.  Attribute identifiers are
              typically given in hexadecimal in which case the hex number should be prefixed by "0x"  or  has  a
              trailing  "h".  "-1" is the default value and means 'match all'; for all other values of FL on the
              matching attribute is output.

       -F, --first=FAI
              where FAI is the "first attribute identifier" field in the cdb. It seems as though the  intent  of
              this  field  is  that  only  attributes  whose  identifiers  are  equal to or greater than FAI are
              returned. The default value of FAI is zero. Attributes are returned in ascending identifier order.

       -h, --help
              output the usage message then exit.

       -H, --hex
              output the response in hexadecimal to stdout. When used once the whole response is output in ASCII
              hexadecimal with a leading address (starting at 0) on each line. When used  twice  each  attribute
              descriptor  in  the  response  is  output  separately  in  hexadecimal. When used thrice the whole
              response is output in hexadecimal with no leading address (on each line).
              Output generated by '-HHH' (or --hex used three times) can be redirected to a file. That file will
              be in suitable format for --in=FN to use in a later invocation.

       -i, --in=FNFN is treated as a file name (or '-'  for  stdin)  which  contains  ASCII  hexadecimal  or  binary
              representing  the  response  to  a  READ  ATTRIBUTE  command  with service action 0x0 (i.e (fetch)
              attribute values). When this option is given then DEVICE (if also given) is ignored.
              By default FN is assumed to contain ASCII hexadecimal arranged as bytes  which  a  space,  tab  or
              comma  delimited.  All  characters from (and including) "#" to the end of line are ignored. If the
              --raw option is also given then FN is assumed to contain binary data. When  the  --raw  option  is
              given  then after processing the input the internal raw variable is reset to 0 so it has no effect
              on the output.
              Since the READ ATTRIBUTE response does not contain the service action number that it is a response
              to, then the --sa=SA should be given (if not service action 0 (attribute values) is assumed.

       -l, --lvn=LVN
              where LVN is placed in the "logical volume number" field of the cdb.  The default  value  is  zero
              which is required to be the logical volume number if the device only has one volume.

       -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 8192 is used. The maximum allowed value of LEN is
              1048576.

       -p, --pn=PN
              where PN is placed in the "partition number" field  of  the  cdb.  If  the  DEVICE  only  has  one
              partition then its partition number must be zero. The default value of PN is zero.

       -q, --quiet
              this  option  reduces  the  amount  of  information  output. For example when used once (SA=0), it
              suppresses the header line announcing the output of attributes; when used twice it suppresses  the
              name of each attribute, leaving only the associated attribute values (or strings).

       -r, --raw
              output the SCSI response (i.e. the data-out buffer) 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, --sa=SA
              where SA is placed on the "service action" field of the cdb. Values of 0 to 63 are accepted with a
              default of 0. spc5r08.pdf defines five service actions:  0  for  attributes  values  ;  1  for  an
              attribute  list (names, not values), 2 for the logical volume list; 3 for the partition list; 4 is
              restricted for SMC-3; and 5 for the supported attribute list.
              Alternatively an acronym can be given for SA. The acronym should be  one  of  "av",  "al",  "lvl",
              "pn",  "smc"  or  "sa"  for service actions 0 to 5 respectively. The acronyms can also be given in
              upper case.

       -v, --verbose
              increase the level of verbosity, (i.e. debug output).

       -V, --version
              print the version string and then exit.

       Report bugs to <dgilbert at interlog dot com>.

sg_vpd,sg_logs(sg3_utils)

sg3_utils-1.46                                    December 2020                                  SG_READ_ATTR(8)

sg_read_attr  [--cache]  [--enumerate]  [--ea=EA]  [--filter=FL] [--first=FAI] [--help] [--hex] [--in=FN]
       [--lvn=LVN] [--maxlen=LEN] [--pn=PN] [--quiet] [--raw]  [--readonly]  [--sa=SA]  [--verbose]  [--version]
       DEVICE