1SG_READ_ATTR(8)                    SG3_UTILS                   SG_READ_ATTR(8)
2
3
4

NAME

6       sg_read_attr - send SCSI READ ATTRIBUTE command
7

SYNOPSIS

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

DESCRIPTION

15       Sends a SCSI READ ATTRIBUTE command to  DEVICE  and  outputs  the  data
16       returned.  This  command was introduced in SPC-3 revision 1 and thus is
17       applicable 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

OPTIONS

22       Arguments to long options are mandatory for short options as well.
23
24       -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
30       -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
35       -E, --ea=EA
36              where  EA  is  an  element  address  which is placed in the READ
37              ATTRIBUTE cdb. This field is  only  found  in  SMC-2  and  SMC-3
38              drafts   for   medium  changers  usually  associated  with  tape
39              libraries. By default this field is set to zero.
40
41       -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
48       -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
51              attributes whose identifiers are equal to or  greater  than  FAI
52              are  returned.  The default value of FAI is zero. Attributes are
53              returned in ascending identifier order.
54
55       -h, --help
56              output the usage message then exit.
57
58       -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
61              address (starting at 0) on  each  line.  When  used  twice  each
62              attribute  descriptor  in  the  response is output separately in
63              hexadecimal. When used thrice the whole response  is  output  in
64              hexadecimal 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
69       -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
81              effect 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
86       -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
91       -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
97       -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
102       -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
105              announcing the output of attributes; when  used  twice  it  sup‐
106              presses  the name of each attribute, leaving only the associated
107              attribute values (or strings).
108
109       -r, --raw
110              output the SCSI response (i.e. the data-out  buffer)  in  binary
111              (to stdout).
112
113       -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
117       -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
126              actions  0  to 5 respectively. The acronyms can also be given in
127              upper case.
128
129       -v, --verbose
130              increase the level of verbosity, (i.e. debug output).
131
132       -V, --version
133              print the version string and then exit.
134

NOTES

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
138       device types could use it.
139
140       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

EXAMPLES

145       To list the attributes of a tape drive whose xxxx is /dev/sg1 the  fol‐
146       lowing could be used:
147
148       # 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
159       To check the number of partitions:
160
161       # sg_read_attr -s pl /dev/sg1
162       Partition number list:
163         First partition number: 0
164         Number of partitions available: 2
165
166       And to see the attribute values (which is the default service action):
167
168       # 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
175       To redirect the attribute values response to a file for later decoding:
176
177       # sg_read_attr -HHH /dev/sg1 > av.hex
178
179       And later the response held in the av.hex file could be decoded with:
180
181       # 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

EXIT STATUS

189       The  exit  status of sg_read_attr is 0 when it is successful. Otherwise
190       see the sg3_utils(8) man page.
191

AUTHORS

193       Written by Douglas Gilbert.
194

REPORTING BUGS

196       Report bugs to <dgilbert at interlog dot com>.
197
199       Copyright © 2016-2017 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

SEE ALSO

205       sg_vpd,sg_logs(sg3_utils)
206
207
208
209sg3_utils-1.43                   November 2017                 SG_READ_ATTR(8)
Impressum