diff options
Diffstat (limited to 'doc/sg_read_attr.8')
| -rw-r--r-- | doc/sg_read_attr.8 | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/doc/sg_read_attr.8 b/doc/sg_read_attr.8 new file mode 100644 index 00000000..8ab59b97 --- /dev/null +++ b/doc/sg_read_attr.8 @@ -0,0 +1,214 @@ +.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) |