Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Wednesday, July 27, 2022

sg_read_attr (8)


sg_read_attr - send SCSI READ ATTRIBUTE command


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] [--ver-
sion] DEVICE


SG_READ_ATTR(8)                    SG3_UTILS                   SG_READ_ATTR(8)

       sg_read_attr - send SCSI READ ATTRIBUTE command

       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] [--ver-
       sion] DEVICE

       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

       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 log-
              ical 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  exam-
              ple  when  used  once  (SA=0),  it  suppresses  the  header line
              announcing the output of attributes; when  used  twice  it  sup-
              presses  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.

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

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

       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.

       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.

       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.

       Written by Douglas Gilbert.

       Report bugs to <dgilbert at interlog dot com>.

       Copyright (C) 2016-2020 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.46                   December 2020                 SG_READ_ATTR(8)