1SG_LOGS(8) SG3_UTILS SG_LOGS(8)
2
6 sg_logs - access log pages with SCSI LOG SENSE command
7
9 sg_logs [--All] [--all] [--brief] [--filter=FL] [--hex] [--list]
10 [--maxlen=LEN] [--name] [--no_inq] [--page=PG] [--paramp=PP] [--pcb]
11 [--ppc] [--pdt=DT] [--raw] [--readonly] [--sp] [--temperature]
12 [--transport] [--vendor=VP] [--verbose] DEVICE
13 sg_logs [--brief] [--filter=FL] [--hex] --in=FN [--name] [--pdt=DT]
15 [--raw] [--vendor=VP]
16 sg_logs [--control=PC] [--in=FN] [--page=PG] [--raw] [--reset] --select
18 [--sp] [--verbose] DEVICE
19 sg_logs [--enumerate] [--filter=FL] [--help] [--vendor=VP] [--version]
21 sg_logs [-a] [-A] [-b] [-D=DT] [-c=PC] [-e] [-f=FL] [-h] [-H] [-i=FN]
23 [-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb] [-ppc] [-r]
24 [-R] [-select] [-sp] [-t] [-T] [-v] [-V] [-?] [-x] DEVICE
25
27 This utility sends a SCSI LOG SENSE command to the DEVICE and then out‐
28 puts the response. The LOG SENSE command is used to fetch log pages
29 which, if known, are decoded by default. When the --reset and/or
30 --select option is given then a SCSI LOG SELECT command is issued to
31 the DEVICE. Alternatively one or more log page responses can be in a
32 file read using the --in=FN option; in this case those responses are
33 decoded and the DEVICE argument, if given, is ignored.
34 In SPC-4 revision 5 a subpage code was introduced to both the LOG SENSE
36 and LOG SELECT command. At the same time a page code field was intro‐
37 duced to the to the LOG SELECT command. The log subpage code can range
38 from 0 to 255 (0xff) inclusive. The subpage code value 255 can be
39 thought of as a wildcard.
40 The SYNOPSIS section above is divided into five forms. The first form
42 shows the options that can be used to send a LOG SENSE command to the
43 DEVICE and decode its response. The second form fetches data from a
44 file (named FN) and decodes it as if it were a response from a LOG
45 SENSE command. The third form shows the options that can be used to
46 send a LOG SELECT command. The fourth form groups various management
47 options. The last form shows the older, deprecated command line inter‐
48 face which is maintained for backward compatibility.
49
51 Arguments to long options are mandatory for short options as well. The
52 options are arranged in alphabetical order based on the long option
53 name.
54 -A, --All
56 fetch and decode all the log pages and subpages supported by the
57 DEVICE. This requires a two stage process: first the "supported
58 log pages and subpages" log page is fetched, then for each entry
59 in its response, the corresponding log page (or subpage) is
60 fetched and displayed. Note that there are many SCSI devices
61 that do not support LOG SENSE subpages and respond to this
62 option with an illegal request sense key (or ignored the subpage
63 field).
64 -a, --all
66 outputs all the log pages supported by the DEVICE. This requires
67 a two stage process: first the "supported log pages" log page is
68 fetched, then for each entry in its response, the corresponding
69 log page is fetched and displayed. When used twice (e.g. '-aa')
70 all log pages and subpages are fetched.
71 -b, --brief
73 shorten the amount of output for some log pages. For example the
74 Tape Alert log page only outputs parameters whose flags are set
75 when --brief is given.
76 -c, --control=PC
78 accepts 0, 1, 2 or 3 for the PC argument:
79 0 : current threshold values
80 1 : current cumulative values
81 2 : default threshold values
82 3 : default cumulative values
83 The default value is 1 (i.e. current cumulative values).
84 -e, --enumerate
86 this option is used to output information held in internal
87 tables about known log pages including their name, acronym and
88 fields. If given, the DEVICE argument is ignored. When given
89 once (e.g. '-e') all known pages are listed, sorted in ascending
90 acronym order (alphabetic). When given twice, vendor pages are
91 excluded. When given three times, all known pages are listed,
92 sorted in ascending numeric order listed; when given four times,
93 vendor pages are excluded from the numeric order.
94 The --filter=FL and --verbose options reduce the output of the
95 enumeration.
96 -f, --filter=FL
98 FL is either a parameter code when DEVICE is given, or a periph‐
99 eral device type (pdt) (or other) if --enumerate is given.
100 In the parameter code case FL is a value between 0 and 65535
101 (0xffff) and only the parameter section matching that code is
102 output. If the --hex option is given the log parameter is output
103 in hexadecimal rather than decoding it. If the --hex option is
104 used twice then the leading address on each line of hex is
105 removed. If the --raw option is given then the log parameter is
106 output in binary. Most log pages contain one or more log parame‐
107 ters. Examples of those that don't follow that convention are
108 those pages that list supported log pages (and subpages).
109 In the --enumerate case, when FL >= zero it is taken as a pdt
110 value and only log pages associated with that pdt plus generic
111 pages listed in SPC are enumerated. If FL is -1 then the filter
112 does nothing which is the same as not giving this option; when
113 FL is -2 then only generic pages listed in SPC are enumerated.
114 If FL is -10 then only generic direct access like (e.g. disk)
115 pages are enumerated. If FL is -11 then only generic tape like
116 pages (e.g. includes ADC) are enumerated.
117 -h, --help
119 print out the usage message then exit.
120 -H, --hex
122 The default action is to decode known log page numbers (and sub‐
123 page numbers) into text. When this option is used once, the
124 response is output in hexadecimal. When used twice, each line of
125 hex has the ASCII equivalent shown to the right. When used three
126 times, the hex has no leading address nor trailing ASCII making
127 it suitable to be placed in a file (or piped). That file might
128 later be used by another invocation using the --in=FN option.
129 -i, --in=FN
131 This option may be used in two different contexts. One is with
132 the --select to send a LOG SELECT command to the given DEVICE;
133 see the LOG SELECT section below.
134 The other context is with no DEVICE argument given in which case
135 the contents of FN are decoded as if it were the response of a
136 LOG SENSE command (i.e. a log page). For decoding the page and
137 subpage numbers are taken from FN while the peripheral device
138 type is either generic (i.e. from SPC) or the value given by
139 --pdt=DT.
140 FN is treated as a file name (or '-' for stdin) which contains
141 ASCII hexadecimal or binary representing a log page. The hexa‐
142 decimal should be arranged as 1 or 2 digits representing a byte
143 each of which is whitespace or comma separated. Anything from
144 and including a hash mark to the end of line is ignored. If the
145 --raw option is also given then FN is treated as binary.
146 -l, --list
148 lists the names of all logs sense pages supported by this
149 device. This is done by reading the "supported log pages" log
150 page. When used twice (e.g. '-ll') lists the names of all logs
151 sense pages and subpages supported by this device. There is a
152 list of common log page codes below.
153 -m, --maxlen=LEN
155 sets the "allocation length" field in the LOG SENSE cdb. The is
156 the maximum length in bytes that the response will be. Without
157 this option (or LEN equal to 0) this utility first fetches the 4
158 byte response then does a second access with the length indi‐
159 cated in the first (4 byte) response. Negative values and 1 for
160 LEN are not accepted. LEN cannot exceed 65535 (0xffff).
161 Responses can be quite large (e.g. the background scan results
162 log page) and this option can be used to limit the amount of
163 information returned.
164 -n, --name
166 decode some log pages into 'name=value' entries, one per line.
167 The name contains no space and may be abbreviated and the value
168 is decimal unless prefixed by '0x'. Nesting is indicated by
169 leading spaces. This form is meant to be relatively easy to
170 parse.
171 -x, --no_inq
173 suppresses the output of information obtained from an initial
174 call to the INQUIRY command for the standard response. The
175 default (assuming some other options that suppress this output
176 are also not given) is to output several device identification
177 strings.
178 If this option is given twice (or more) then no INQUIRY command
179 is sent hence there will be no device identification string out‐
180 put either. Also the peripheral device type (PDT) field will not
181 be obtained so this utility will not be able to differentiate
182 between some log pages that are device dependent. It will assume
183 a PDT of 0 (i.e. a disk).
184 -O, --old
186 Switch to older style options. Please use as first option.
187 -p, --page=PG
189 log page name/number to access. PG is either an acronym, a page
190 number, or a page, subpage number pair. Available acronyms can
191 be listed with the --enumerate option. Page (0 to 63) and sub‐
192 page (0 to 255) numbers are comma separated. They are decimal
193 unless a hexadecimal indication is given. A hexadecimal number
194 can be specified by a leading "0x" or a trailing "h".
195 A few acronyms specify a range of subpage values in which case
196 the acronym may be followed by a comma then a subpage number.
197 This method can also be used to fetch the Supported subpages log
198 page (e.g. --page=temp,0xff).
199 -P, --paramp=PP
201 PP is the parameter pointer value to place in a field of that
202 name in the LOG SENSE cdb. A decimal number in the range 0 to
203 65535 (0xffff) is expected. When a value greater than 0 is given
204 the --ppc option should be selected. The default value is 0.
205 -q, --pcb
207 show Parameter Control Byte settings (only relevant when log
208 parameters being output in ASCII).
209 -Q, --ppc
211 sets the Parameter Pointer Control (PPC) bit in the LOG SENSE
212 cdb. Default is 0 (i.e. cleared). This bit was made obsolete in
213 SPC-4 revision 18.
214 -D, --pdt=DT
216 DT is the peripheral device type that is used when it is not
217 available from the DEVICE. There are two main cases of this:
218 with the --pdt=DT without a DEVICE and when --no_inq is used
219 with a DEVICE.
220 -r, --raw
222 output the response in binary to stdout. Error messages and
223 warnings are output to stderr.
224 This option may also be given together with --in=FN in which
225 case the contents of FN are interpreted as binary data (and the
226 response is decoded as normal, not dumped as binary).
227 -R, --readonly
229 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
230 The default action is to try and open DEVICE read-write then if
231 that fails try to open again with read-only. However when a
232 read-write open succeeds there may still be unwanted actions on
233 the close (e.g. some OSes try to do a SYNCHRONIZE CACHE com‐
234 mand). So this option forces a read-only open on DEVICE and if
235 it fails, this utility will exit. Note that options like
236 --select most likely need a read-write open.
237 -R, --reset
239 use SCSI LOG SELECT command (with the PCR bit set) to reset the
240 all log pages (or the given page). Exactly what is reset depends
241 on the accompanying SP bit (i.e. --sp option which defaults to
242 0) and the PC ("page control") value (which defaults to 1). Sup‐
243 plying this option implies the --select option as well. This
244 option seems to clear error counter log pages but leaves pages
245 like self-test results, start-stop cycle counter and temperature
246 log pages unaffected. This option may be required to clear log
247 pages if a counter reaches its maximum value since the log page
248 in which the counter is found will remain "stuck" at its maximum
249 value until some user interaction (e.g. calling sg_logs with
250 this option).
251 -S, --select
253 use a LOG SELECT command. The default action (i.e. when neither
254 this option nor --reset is given) is to do a LOG SENSE command.
255 See the LOG SELECT section.
256 -s, --sp
258 sets the Saving Parameters (SP) bit. Default is 0 (i.e.
259 cleared). When set this instructs the device to store the cur‐
260 rent log page parameters (as indicated by the DS and TSD parame‐
261 ter codes) in some non-volatile location. Hence the log parame‐
262 ters will be preserved across power cycles. This option is typi‐
263 cally not needed, especially if the GLTSD flag is clear in the
264 control mode page as this instructs the device to periodically
265 save all saveable log parameters to non-volatile locations.
266 -t, --temperature
268 outputs the temperature. First looks in the temperature log page
269 and if that is not available tries the Informational Exceptions
270 log page which may also have the current temperature (especially
271 on older disks).
272 -T, --transport
274 outputs the transport ('Protocol specific port') log page.
275 Equivalent to setting '--page=18h'.
276 -M, --vendor=VP
278 where VP is a vendor (e.g. "sea" for Seagate) or product (group)
279 acronym (e.g. "lto5" for the 5th generation LTO (tape) consor‐
280 tium). Either the whole log page is vendor specific (e.g. page
281 numbers 0x30 to 0x3f) or part of a T10 defined log page is ven‐
282 dor specific. For example SPC-5 defines parameter code 0x0 of
283 page 0x2f (the Informational Exceptions log page) and states
284 that the remaining parameter codes (i.e. 0x1 to 0xffff) are ven‐
285 dor specific. Using a VP of "xxx" will list the available
286 acronyms.
287 If this option is used with --page=PG and PG is an acronym then
288 this option is ignored. If PG is a number (e.g. 0xc0) then VP is
289 used to choose the which vendor specific page (e.g. sharing page
290 number 0xc0) to decode.
291 -v, --verbose
293 increase level of verbosity. When used with --enumerate, in the
294 list of known log page names, those that have no associated
295 decode logic are followed by "[hex only]".
296 -V, --version
298 print out version string then exit.
299
301 The SCSI LOG SELECT command can be used to reset certain parameters to
302 vendor specific defaults, save them to non-volatile storage (i.e. the
303 media), or supply new page contents. This command has changed between
304 SPC-3 and SPC-4 with the addition of the Page and Subpage Code fields
305 which can only be non zero when the Parameter list length is zero.
306 The --select (or --reset) option is required to issue a LOG SELECT com‐
308 mand. If the --in=FN option is not given (or FN is effectively empty)
309 then the Parameter list length field is set to zero. If the --in=FN
310 option is is given then its decoded data is placed in the data-out buf‐
311 fer and its length in bytes is placed in the Parameter list length
312 field.
313 Other options that are active with the LOG SELECT command are --con‐
315 trol=PC, --reset (which sets the PCR bit) and --sp.
316
318 This is the name of a log page that acts as a container for data pro‐
319 vided by the user. An application client is a SCSI term for the program
320 that issues commands to a SCSI initiator (often known as a Host Bus
321 Adapter (HBA)). So, for example, this utility is a SCSI application
322 client.
323 The Application Client log page has 64 log parameters with parameters
325 codes 0 to 63. Each can hold 252 bytes of user binary data. That 252
326 bytes (or less) of user data, with a 4 byte prefix (for a total of 256
327 bytes) can be provided with the --in=FN option. A typical prefix would
328 be '0,n,83,fc'. The "n" is the parameter code in hex so the last log
329 parameter would be '0,3f,83,fc'. That log parameter could be read back
330 at some later time with '--page=0xf --filter=0x<n>'.
331
333 This utility will usually do a double fetch of log pages with the SCSI
334 LOG SENSE command. The first fetch requests a 4 byte response (i.e.
335 place 4 in the "allocation length" field in the cdb). From that
336 response it can calculate the actual length of the response which is
337 what it asks for on the second fetch. This is typical practice in SCSI
338 and guaranteed to work in the standards. However some older devices
339 don't comply. For those devices using the --maxlen=LEN option will do a
340 single fetch. A value of 252 should be a safe starting point.
341 Various log pages hold information error rates, device temperature,
343 start stop cycles since the device was produced and the results of the
344 last 20 self tests. Self tests can be initiated by the sg_senddiag(8)
345 utility. The smartmontools package provides much of the information
346 found with sg_logs in a form suitable for monitoring the health of SCSI
347 disks and tape drives.
348 The simplest way to find which log pages can be decoded by this utility
350 is to use the --enumerate option. Some page names are known but there
351 is no decode logic; such cases have "[hex only]" after the log page
352 name when the --verbose option is given with --enumerate.
353
355 The exit status of sg_logs is 0 when it is successful. Otherwise see
356 the sg3_utils(8) man page.
357
359 The options in this section were the only ones available prior to
360 sg3_utils version 1.23 . Since then this utility defaults to the newer
361 command line options which can be overridden by using --old (or -O) as
362 the first option. See the ENVIRONMENT VARIABLES section for another way
363 to force the use of these older command line options.
364 Options with arguments or with two or more letters can have an extra
366 '-' prepended. For example: both '-pcb' and '--pcb' are acceptable.
367 -a outputs all the log pages supported by the device. Equivalent
369 to --all in the main description.
370 -A outputs all the log pages and subpages supported by the device.
372 Equivalent to '--all --all' in the main description.
373 -c=PC Equivalent to --control=PC in the main description.
375 -e enumerate internal tables to show information about known log
377 pages. Equivalent to --enumerate in the main description.
378 -h suppresses decoding of known log sense pages and prints out the
380 response in hex instead.
381 -i=FN FN is treated as a file name (or '-' for stdin) which contains
383 ASCII hexadecimal representing a log page that will be sent as
384 parameter data of a LOG SELECT command. See the LOG SELECT sec‐
385 tion.
386 -H same action as '-h' in this section and equivalent to --hex in
388 the main description.
389 -l lists the names of all logs sense pages supported by this
391 device. Equivalent to --list in the main description.
392 -L lists the names of all logs sense pages and subpages supported
394 by this device. Equivalent to '--list --list' in the main
395 description.
396 -m=LEN request only LEN bytes of response data. Default is 0 which is
398 interpreted as all that is available. LEN is decimal unless it
399 has a leading '0x' or trailing 'h'. Equivalent to --maxlen=LEN
400 in the main description.
401 -M=VP Equivalent to --vendor=VP in the main description.
403 -n Equivalent to --name in the main description.
405 -N, --new
407 Switch to the newer style options.
408 -p=PG log page code to access. PG is either an acronym, a page number,
410 or a page, subpage pair. Available acronyms can be listed with
411 the --enumerate option. Page (0 to 3f) and subpage (0 to ff)
412 numbers are comma separated. The numbers are assumed to be hexa‐
413 decimal.
414 -paramp=PP
416 PP is the parameter pointer value (in hex) to place in command.
417 Should be a number between 0 and ffff inclusive.
418 -pcb show Parameter Control Byte settings (only relevant when log
420 parameters being output in ASCII).
421 -ppc sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e.
423 cleared).
424 -r use SCSI LOG SELECT command (PCR bit set) to reset the all log
426 pages (or the given page). Equivalent to --reset in the main
427 description.
428 -R Equivalent to --readonly in the main description.
430 -select
432 use a LOG SELECT command. Equivalent to --select in the main
433 description.
434 -sp sets the Saving Parameters (SP) bit. Default is 0 (i.e.
436 cleared). Equivalent to --sp in the main description.
437 -t outputs the temperature. Equivalent to --temperature in the main
439 description.
440 -T outputs the transport ('Protocol specific port') log page.
442 Equivalent to --transport in the main description.
443 -v increase level of verbosity.
445 -V print out version string then exit.
447 -x suppress the INQUIRY command. Equivalent to --no_inq in the main
449 description.
450 -? output usage message then exit.
452
454 Since sg3_utils version 1.23 the environment variable
455 SG3_UTILS_OLD_OPTS can be given. When it is present this utility will
456 expect the older command line options. So the presence of this environ‐
457 ment variable is equivalent to using --old (or -O) as the first command
458 line option.
459
461 Written by Douglas Gilbert
462
464 Report bugs to <dgilbert at interlog dot com>.
465
467 Copyright © 2002-2018 Douglas Gilbert
468 This software is distributed under the GPL version 2. There is NO war‐
469 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
470 POSE.
471
473 smartctl(smartmontools), sg_senddiag(8)
474sg3_utils-1.43 August 2018 SG_LOGS(8)