phpman > man > sg_read_attr(8)

SG_READ_ATTR(8)                               SG3_UTILS                              SG_READ_ATTR(8)



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  re‐
              turn  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 identi‐
              fiers are typically given in hexadecimal in which case the hex number should  be  pre‐
              fixed  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 hexadeci‐
              mal. When used thrice the whole response is output in hexadecimal with no leading  ad‐
              dress (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  vari‐
              able 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 "allo‐
              cation length" field. If not given (or LEN is zero) then 8192 is used. The maximum al‐
              lowed 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 ac‐
              cepted 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 MER‐
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO
       sg_vpd,sg_logs(sg3_utils)



sg3_utils-1.46                              December 2020                            SG_READ_ATTR(8)