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