1SG_READ_ATTR(8) SG3_UTILS SG_READ_ATTR(8)
2
6 sg_read_attr - send SCSI READ ATTRIBUTE command
7
9 sg_read_attr [--cache] [--enumerate] [--ea=EA] [--filter=FL]
10 [--first=FAI] [--help] [--hex] [--in=FN] [--lvn=LVN] [--maxlen=LEN]
11 [--pn=PN] [--quiet] [--raw] [--readonly] [--sa=SA] [--verbose] [--ver‐
12 sion] DEVICE
13
15 Sends a SCSI READ ATTRIBUTE command to DEVICE and outputs the data re‐
16 turned. This command was introduced in SPC-3 revision 1 and thus is ap‐
17 plicable to all SCSI devices. In practice it is used mainly for tape
18 systems. This utility is based on the SPC-5 draft standard, revision 17
19 (spc5r17.pdf).
20
22 Arguments to long options are mandatory for short options as well.
23 -c, --cache
25 sets the CACHE bit in the READ ATTRIBUTE cdb. This instructs the
26 device server to return cached attributes. By default that bit
27 is cleared which instructs the device server not to return
28 cached attributes.
29 -e, --enumerate
31 enumerates all known attributes and service actions. Attributes
32 include an identifier, length, format and a name as defined by
33 T10. If DEVICE is given then it is ignored.
34 -E, --ea=EA
36 where EA is an element address which is placed in the READ AT‐
37 TRIBUTE cdb. This field is only found in SMC-2 and SMC-3 drafts
38 for medium changers usually associated with tape libraries. By
39 default this field is set to zero.
40 -f, --filter=FL
42 where FL is an attribute identifier in the range 0 to 65535 or
43 -1. Attribute identifiers are typically given in hexadecimal in
44 which case the hex number should be prefixed by "0x" or has a
45 trailing "h". "-1" is the default value and means 'match all';
46 for all other values of FL on the matching attribute is output.
47 -F, --first=FAI
49 where FAI is the "first attribute identifier" field in the cdb.
50 It seems as though the intent of this field is that only at‐
51 tributes whose identifiers are equal to or greater than FAI are
52 returned. The default value of FAI is zero. Attributes are re‐
53 turned in ascending identifier order.
54 -h, --help
56 output the usage message then exit.
57 -H, --hex
59 output the response in hexadecimal to stdout. When used once the
60 whole response is output in ASCII hexadecimal with a leading ad‐
61 dress (starting at 0) on each line. When used twice each attri‐
62 bute descriptor in the response is output separately in hexadec‐
63 imal. When used thrice the whole response is output in hexadeci‐
64 mal with no leading address (on each line).
65 Output generated by '-HHH' (or --hex used three times) can be
66 redirected to a file. That file will be in suitable format for
67 --in=FN to use in a later invocation.
68 -i, --in=FN
70 FN is treated as a file name (or '-' for stdin) which contains
71 ASCII hexadecimal or binary representing the response to a READ
72 ATTRIBUTE command with service action 0x0 (i.e (fetch) attribute
73 values). When this option is given then DEVICE (if also given)
74 is ignored.
75 By default FN is assumed to contain ASCII hexadecimal arranged
76 as bytes which a space, tab or comma delimited. All characters
77 from (and including) "#" to the end of line are ignored. If the
78 --raw option is also given then FN is assumed to contain binary
79 data. When the --raw option is given then after processing the
80 input the internal raw variable is reset to 0 so it has no ef‐
81 fect on the output.
82 Since the READ ATTRIBUTE response does not contain the service
83 action number that it is a response to, then the --sa=SA should
84 be given (if not service action 0 (attribute values) is assumed.
85 -l, --lvn=LVN
87 where LVN is placed in the "logical volume number" field of the
88 cdb. The default value is zero which is required to be the log‐
89 ical volume number if the device only has one volume.
90 -m, --maxlen=LEN
92 where LEN is the (maximum) response length in bytes. It is
93 placed in the cdb's "allocation length" field. If not given (or
94 LEN is zero) then 8192 is used. The maximum allowed value of LEN
95 is 1048576.
96 -p, --pn=PN
98 where PN is placed in the "partition number" field of the cdb.
99 If the DEVICE only has one partition then its partition number
100 must be zero. The default value of PN is zero.
101 -q, --quiet
103 this option reduces the amount of information output. For exam‐
104 ple when used once (SA=0), it suppresses the header line an‐
105 nouncing the output of attributes; when used twice it suppresses
106 the name of each attribute, leaving only the associated attri‐
107 bute values (or strings).
108 -r, --raw
110 output the SCSI response (i.e. the data-out buffer) in binary
111 (to stdout).
112 -R, --readonly
114 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
115 The default is to open it read-write.
116 -s, --sa=SA
118 where SA is placed on the "service action" field of the cdb.
119 Values of 0 to 63 are accepted with a default of 0. spc5r08.pdf
120 defines five service actions: 0 for attributes values ; 1 for an
121 attribute list (names, not values), 2 for the logical volume
122 list; 3 for the partition list; 4 is restricted for SMC-3; and 5
123 for the supported attribute list.
124 Alternatively an acronym can be given for SA. The acronym should
125 be one of "av", "al", "lvl", "pn", "smc" or "sa" for service ac‐
126 tions 0 to 5 respectively. The acronyms can also be given in up‐
127 per case.
128 -v, --verbose
130 increase the level of verbosity, (i.e. debug output).
131 -V, --version
133 print the version string and then exit.
134
136 Only tape systems seem to implement the SCSI READ ATTRIBUTE command.
137 The vast majority of its definition is in the SPC standard so other de‐
138 vice types could use it.
139 Much of the information provided by READ ATTRIBUTE can also be found in
141 pages returned by LOG SENSE (see the sg_logs utility) and in the VPD
142 pages returned by the INQUIRY command.
143
145 To list the attributes of a tape drive whose DEVICE is /dev/sg1 , the
146 following could be used:
147 # sg_read_attr -s al /dev/sg1
149 Attribute list:
150 Remaining capacity in partition [MiB]
151 Maximum capacity in partition [MiB]
152 TapeAlert flags
153 Load count
154 MAM space remaining [B]
155 Assigning organization
156 Format density code
157 ...
158 To check the number of partitions:
160 # sg_read_attr -s pl /dev/sg1
162 Partition number list:
163 First partition number: 0
164 Number of partitions available: 2
165 And to see the attribute values (which is the default service action):
167 # sg_read_attr /dev/sg1
169 Attribute values:
170 Remaining capacity in partition [MiB]: 1386103
171 Maximum capacity in partition [MiB]: 1386103
172 TapeAlert flags: 0
173 ....
174 To redirect the attribute values response to a file for later decoding:
176 # sg_read_attr -HHH /dev/sg1 > av.hex
178 And later the response held in the av.hex file could be decoded with:
180 # sg_read_attr -s av --in=av.hex
182 Attribute values:
183 Remaining capacity in partition [MiB]: 1386103
184 Maximum capacity in partition [MiB]: 1386103
185 TapeAlert flags: 0
186 ....
187
189 The exit status of sg_read_attr is 0 when it is successful. Otherwise
190 see the sg3_utils(8) man page.
191
193 Written by Douglas Gilbert.
194
196 Report bugs to <dgilbert at interlog dot com>.
197
199 Copyright © 2016-2020 Douglas Gilbert
200 This software is distributed under a FreeBSD license. There is NO war‐
201 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
202 POSE.
203
205 sg_vpd,sg_logs(sg3_utils)
206sg3_utils-1.46 December 2020 SG_READ_ATTR(8)