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] [--version] 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
(spc5r17.pdf).
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.
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.
To list the attributes of a tape drive whose xxxx 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 © 2016-2017 Douglas Gilbert
This software is distributed under a FreeBSD license. There is NO warranty;
not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
sg_vpd,sg_logs(sg3_utils)