Provided by: sg3-utils_1.46-3ubuntu4_amd64 bug

NAME

       sg_read_attr - send SCSI READ ATTRIBUTE command

SYNOPSIS

       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

DESCRIPTION

       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).

OPTIONS

       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=FN
              FN 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.

NOTES

       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.

EXAMPLES

       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
         ....

EXIT STATUS

       The exit status of sg_read_attr 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 © 2016-2020 Douglas Gilbert
       This software is distributed under a FreeBSD license. There is NO warranty; not  even  for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       sg_vpd,sg_logs(sg3_utils)