path: root/doc/sg_read_attr.8

.TH SG_READ_ATTR "8" "December 2020" "sg3_utils\-1.46" SG3_UTILS
.SH NAME
sg_read_attr \- send SCSI READ ATTRIBUTE command
.SH SYNOPSIS
.B sg_read_attr
[\fI\-\-cache\fR] [\fI\-\-enumerate\fR] [\fI\-\-ea=EA\fR]
[\fI\-\-filter=FL\fR] [\fI\-\-first=FAI\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
[\fI\-\-in=FN\fR] [\fI\-\-lvn=LVN\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-pn=PN\fR]
[\fI\-\-quiet\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-sa=SA\fR]
[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
Sends a SCSI READ ATTRIBUTE command to \fIDEVICE\fR 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).
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-c\fR, \fB\-\-cache\fR
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.
.TP
\fB\-e\fR, \fB\-\-enumerate\fR
enumerates all known attributes and service actions. Attributes include
an identifier, length, format and a name as defined by T10. If \fIDEVICE\fR
is given then it is ignored.
.TP
\fB\-E\fR, \fB\-\-ea\fR=\fIEA\fR
where \fIEA\fR 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.
.TP
\fB\-f\fR, \fB\-\-filter\fR=\fIFL\fR
where \fIFL\fR 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 \fIFL\fR
on the matching attribute is output.
.TP
\fB\-F\fR, \fB\-\-first\fR=\fIFAI\fR
where \fIFAI\fR 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 \fIFAI\fR are returned. The default
value of \fIFAI\fR is zero. Attributes are returned in ascending identifier
order.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-H\fR, \fB\-\-hex\fR
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).
.br
Output generated by '\-HHH' (or \fI\-\-hex\fR used three times) can be
redirected to a file. That file will be in suitable format for \fI\-\-in=FN\fR
to use in a later invocation.
.TP
\fB\-i\fR, \fB\-\-in\fR=\fIFN\fR
\fIFN\fR 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 \fIDEVICE\fR (if also given) is ignored.
.br
By default \fIFN\fR 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 \fI\-\-raw\fR option
is also given then \fIFN\fR is assumed to contain binary data. When the
\fI\-\-raw\fR option is given then after processing the input the
internal raw variable is reset to 0 so it has no effect on the output.
.br
Since the READ ATTRIBUTE response does not contain the service action number
that it is a response to, then the \fI\-\-sa=SA\fR should be given (if not
service action 0 (attribute values) is assumed.
.TP
\fB\-l\fR, \fB\-\-lvn\fR=\fILVN\fR
where \fILVN\fR 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.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
where \fILEN\fR is the (maximum) response length in bytes. It is placed in
the cdb's "allocation length" field. If not given (or \fILEN\fR is zero)
then 8192 is used. The maximum allowed value of \fILEN\fR is 1048576.
.TP
\fB\-p\fR, \fB\-\-pn\fR=\fIPN\fR
where \fIPN\fR is placed in the "partition number" field of the cdb. If
the \fIDEVICE\fR only has one partition then its partition number must be
zero. The default value of \fIPN\fR is zero.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
this option reduces the amount of information output. For example when
used once (\fISA\fR=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).
.TP
\fB\-r\fR, \fB\-\-raw\fR
output the SCSI response (i.e. the data\-out buffer) in binary (to stdout).
.TP
\fB\-R\fR, \fB\-\-readonly\fR
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag).
The default is to open it read\-write.
.TP
\fB\-s\fR, \fB\-\-sa\fR=\fISA\fR
where \fISA\fR 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.
.br
Alternatively an acronym can be given for \fISA\fR. 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.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the level of verbosity, (i.e. debug output).
.TP
\fB\-V\fR, \fB\-\-version\fR
print the version string and then exit.
.SH 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.
.PP
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.
.SH EXAMPLES
To list the attributes of a tape drive whose \fIDEVICE\fR is /dev/sg1 ,
the following could be used:
.PP
# sg_read_attr \-s al /dev/sg1
.br
Attribute list:
.br
  Remaining capacity in partition [MiB]
.br
  Maximum capacity in partition [MiB]
.br
  TapeAlert flags
.br
  Load count
.br
  MAM space remaining [B]
.br
  Assigning organization
.br
  Format density code
.br
  ...
.PP
To check the number of partitions:
.PP
# sg_read_attr \-s pl /dev/sg1
.br
Partition number list:
.br
  First partition number: 0
.br
  Number of partitions available: 2
.PP
And to see the attribute values (which is the default service action):
.PP
# sg_read_attr /dev/sg1
.br
Attribute values:
.br
  Remaining capacity in partition [MiB]: 1386103
.br
  Maximum capacity in partition [MiB]: 1386103
.br
  TapeAlert flags: 0
.br
  ....
.PP
To redirect the attribute values response to a file for later decoding:
.PP
# sg_read_attr \-HHH /dev/sg1 > av.hex
.PP
And later the response held in the av.hex file could be decoded with:
.PP
# sg_read_attr \-s av \-\-in=av.hex
.br
Attribute values:
.br
  Remaining capacity in partition [MiB]: 1386103
.br
  Maximum capacity in partition [MiB]: 1386103
.br
  TapeAlert flags: 0
.br
  ....
.PP
.SH EXIT STATUS
The exit status of sg_read_attr is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2016\-2020 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_vpd,sg_logs(sg3_utils)