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, excluding
152 pages whose subpage number is 0xff (apart from page 0x0,0xff).
153 When used three times then all supported pages and subpages
154 reported by the device are list. So the page/subpage names and
155 not thrie content is shown with this option. There is a list of
156 common log page codes below.
157 -m, --maxlen=LEN
159 sets the "allocation length" field in the LOG SENSE cdb. The is
160 the maximum length in bytes that the response will be. Without
161 this option (or LEN equal to 0) this utility first fetches the 4
162 byte response then does a second access with the length indi‐
163 cated in the first (4 byte) response. Negative values and 1 for
164 LEN are not accepted. LEN cannot exceed 65535 (0xffff).
165 Responses can be quite large (e.g. the background scan results
166 log page) and this option can be used to limit the amount of
167 information returned.
168 -n, --name
170 decode some log pages into 'name=value' entries, one per line.
171 The name contains no space and may be abbreviated and the value
172 is decimal unless prefixed by '0x'. Nesting is indicated by
173 leading spaces. This form is meant to be relatively easy to
174 parse.
175 -x, --no_inq
177 suppresses the output of information obtained from an initial
178 call to the INQUIRY command for the standard response. The
179 default (assuming some other options that suppress this output
180 are also not given) is to output several device identification
181 strings.
182 If this option is given twice (or more) then no INQUIRY command
183 is sent hence there will be no device identification string out‐
184 put either. Also the peripheral device type (PDT) field will not
185 be obtained so this utility will not be able to differentiate
186 between some log pages that are device dependent. It will assume
187 a PDT of 0 (i.e. a disk).
188 -O, --old
190 Switch to older style options. Please use as first option.
191 -p, --page=PG
193 log page name/number to access. PG is either an acronym, a page
194 number, or a page, subpage number pair. Available acronyms can
195 be listed with the --enumerate option. Page (0 to 63) and sub‐
196 page (0 to 255) numbers are comma separated. They are decimal
197 unless a hexadecimal indication is given. A hexadecimal number
198 can be specified by a leading "0x" or a trailing "h".
199 A few acronyms specify a range of subpage values in which case
200 the acronym may be followed by a comma then a subpage number.
201 This method can also be used to fetch the Supported subpages log
202 page (e.g. --page=temp,0xff).
203 -P, --paramp=PP
205 PP is the parameter pointer value to place in a field of that
206 name in the LOG SENSE cdb. A decimal number in the range 0 to
207 65535 (0xffff) is expected. When a value greater than 0 is given
208 the --ppc option should be selected. The default value is 0.
209 -q, --pcb
211 show Parameter Control Byte settings (only relevant when log
212 parameters being output in ASCII).
213 -Q, --ppc
215 sets the Parameter Pointer Control (PPC) bit in the LOG SENSE
216 cdb. Default is 0 (i.e. cleared). This bit was made obsolete in
217 SPC-4 revision 18.
218 -D, --pdt=DT
220 DT is the peripheral device type that is used when it is not
221 available from the DEVICE. There are two main cases of this:
222 with the --pdt=DT without a DEVICE and when --no_inq is used
223 with a DEVICE.
224 -r, --raw
226 output the response in binary to stdout. Error messages and
227 warnings are output to stderr.
228 This option may also be given together with --in=FN in which
229 case the contents of FN are interpreted as binary data (and the
230 response is decoded as normal, not dumped as binary).
231 -R, --readonly
233 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
234 The default action is to try and open DEVICE read-write then if
235 that fails try to open again with read-only. However when a
236 read-write open succeeds there may still be unwanted actions on
237 the close (e.g. some OSes try to do a SYNCHRONIZE CACHE com‐
238 mand). So this option forces a read-only open on DEVICE and if
239 it fails, this utility will exit. Note that options like
240 --select most likely need a read-write open.
241 -R, --reset
243 use SCSI LOG SELECT command (with the PCR bit set) to reset the
244 all log pages (or the given page). Exactly what is reset depends
245 on the accompanying SP bit (i.e. --sp option which defaults to
246 0) and the PC ("page control") value (which defaults to 1). Sup‐
247 plying this option implies the --select option as well. This
248 option seems to clear error counter log pages but leaves pages
249 like self-test results, start-stop cycle counter and temperature
250 log pages unaffected. This option may be required to clear log
251 pages if a counter reaches its maximum value since the log page
252 in which the counter is found will remain "stuck" at its maximum
253 value until some user interaction (e.g. calling sg_logs with
254 this option).
255 -S, --select
257 use a LOG SELECT command. The default action (i.e. when neither
258 this option nor --reset is given) is to do a LOG SENSE command.
259 See the LOG SELECT section.
260 -s, --sp
262 sets the Saving Parameters (SP) bit. Default is 0 (i.e.
263 cleared). When set this instructs the device to store the cur‐
264 rent log page parameters (as indicated by the DS and TSD parame‐
265 ter codes) in some non-volatile location. Hence the log parame‐
266 ters will be preserved across power cycles. This option is typi‐
267 cally not needed, especially if the GLTSD flag is clear in the
268 control mode page as this instructs the device to periodically
269 save all saveable log parameters to non-volatile locations.
270 -t, --temperature
272 outputs the temperature. First looks in the temperature log page
273 and if that is not available tries the Informational Exceptions
274 log page which may also have the current temperature (especially
275 on older disks).
276 -T, --transport
278 outputs the transport ('Protocol specific port') log page.
279 Equivalent to setting '--page=18h'.
280 -M, --vendor=VP
282 where VP is a vendor/manufacturer (e.g. "sea" for Seagate) or
283 product (group) acronym (e.g. "lto5" for the 5th generation LTO
284 (tape) consortium). Either the whole log page is vendor specific
285 (e.g. page numbers 0x30 to 0x3f) or part of a T10 defined log
286 page is vendor specific. For example SPC-5 defines parameter
287 code 0x0 of page 0x2f (the Informational Exceptions log page)
288 and states that the remaining parameter codes (i.e. 0x1 to
289 0xffff) are vendor specific. Using a VP of "xxx" will list the
290 available acronyms.
291 If this option is used with --page=PG and PG is an acronym then
292 this option is ignored. If PG is a number (e.g. 0xc0) then VP is
293 used to choose the which vendor specific page (e.g. sharing page
294 number 0xc0) to decode.
295 -v, --verbose
297 increase level of verbosity. When used with --enumerate, in the
298 list of known log page names, those that have no associated
299 decode logic are followed by "[hex only]".
300 -V, --version
302 print out version string then exit.
303
305 The SCSI LOG SELECT command can be used to reset certain parameters to
306 vendor specific defaults, save them to non-volatile storage (i.e. the
307 media), or supply new page contents. This command has changed between
308 SPC-3 and SPC-4 with the addition of the Page and Subpage Code fields
309 which can only be non zero when the Parameter list length is zero.
310 The --select (or --reset) option is required to issue a LOG SELECT com‐
312 mand. If the --in=FN option is not given (or FN is effectively empty)
313 then the Parameter list length field is set to zero. If the --in=FN
314 option is is given then its decoded data is placed in the data-out buf‐
315 fer and its length in bytes is placed in the Parameter list length
316 field.
317 Other options that are active with the LOG SELECT command are --con‐
319 trol=PC, --reset (which sets the PCR bit) and --sp.
320
322 This is the name of a log page that acts as a container for data pro‐
323 vided by the user. An application client is a SCSI term for the program
324 that issues commands to a SCSI initiator (often known as a Host Bus
325 Adapter (HBA)). So, for example, this utility is a SCSI application
326 client.
327 The Application Client log page has 64 log parameters with parameters
329 codes 0 to 63. Each can hold 252 bytes of user binary data. That 252
330 bytes (or less) of user data, with a 4 byte prefix (for a total of 256
331 bytes) can be provided with the --in=FN option. A typical prefix would
332 be '0,n,83,fc'. The "n" is the parameter code in hex so the last log
333 parameter would be '0,3f,83,fc'. That log parameter could be read back
334 at some later time with '--page=0xf --filter=0x<n>'.
335
337 This utility will usually do a double fetch of log pages with the SCSI
338 LOG SENSE command. The first fetch requests a 4 byte response (i.e.
339 place 4 in the "allocation length" field in the cdb). From that
340 response it can calculate the actual length of the response which is
341 what it asks for on the second fetch. This is typical practice in SCSI
342 and guaranteed to work in the standards. However some older devices
343 don't comply. For those devices using the --maxlen=LEN option will do a
344 single fetch. A value of 252 should be a safe starting point.
345 Various log pages hold information error rates, device temperature,
347 start stop cycles since the device was produced and the results of the
348 last 20 self tests. Self tests can be initiated by the sg_senddiag(8)
349 utility. The smartmontools package provides much of the information
350 found with sg_logs in a form suitable for monitoring the health of SCSI
351 disks and tape drives.
352 The simplest way to find which log pages can be decoded by this utility
354 is to use the --enumerate option. Some page names are known but there
355 is no decode logic; such cases have "[hex only]" after the log page
356 name when the --verbose option is given with --enumerate.
357
359 The exit status of sg_logs is 0 when it is successful. Otherwise see
360 the sg3_utils(8) man page.
361
363 The options in this section were the only ones available prior to
364 sg3_utils version 1.23 . Since then this utility defaults to the newer
365 command line options which can be overridden by using --old (or -O) as
366 the first option. See the ENVIRONMENT VARIABLES section for another way
367 to force the use of these older command line options.
368 Options with arguments or with two or more letters can have an extra
370 '-' prepended. For example: both '-pcb' and '--pcb' are acceptable.
371 -a outputs all the log pages supported by the device. Equivalent
373 to --all in the main description.
374 -A outputs all the log pages and subpages supported by the device.
376 Equivalent to '--all --all' in the main description.
377 -c=PC Equivalent to --control=PC in the main description.
379 -e enumerate internal tables to show information about known log
381 pages. Equivalent to --enumerate in the main description.
382 -h suppresses decoding of known log sense pages and prints out the
384 response in hex instead.
385 -i=FN FN is treated as a file name (or '-' for stdin) which contains
387 ASCII hexadecimal representing a log page that will be sent as
388 parameter data of a LOG SELECT command. See the LOG SELECT sec‐
389 tion.
390 -H same action as '-h' in this section and equivalent to --hex in
392 the main description.
393 -l lists the names of all logs sense pages supported by this
395 device. Equivalent to --list in the main description.
396 -L lists the names of all logs sense pages and subpages supported
398 by this device. Equivalent to '--list --list' in the main
399 description.
400 -m=LEN request only LEN bytes of response data. Default is 0 which is
402 interpreted as all that is available. LEN is decimal unless it
403 has a leading '0x' or trailing 'h'. Equivalent to --maxlen=LEN
404 in the main description.
405 -M=VP Equivalent to --vendor=VP in the main description.
407 -n Equivalent to --name in the main description.
409 -N, --new
411 Switch to the newer style options.
412 -p=PG log page code to access. PG is either an acronym, a page number,
414 or a page, subpage pair. Available acronyms can be listed with
415 the --enumerate option. Page (0 to 3f) and subpage (0 to ff)
416 numbers are comma separated. The numbers are assumed to be hexa‐
417 decimal.
418 -paramp=PP
420 PP is the parameter pointer value (in hex) to place in command.
421 Should be a number between 0 and ffff inclusive.
422 -pcb show Parameter Control Byte settings (only relevant when log
424 parameters being output in ASCII).
425 -ppc sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e.
427 cleared).
428 -r use SCSI LOG SELECT command (PCR bit set) to reset the all log
430 pages (or the given page). Equivalent to --reset in the main
431 description.
432 -R Equivalent to --readonly in the main description.
434 -select
436 use a LOG SELECT command. Equivalent to --select in the main
437 description.
438 -sp sets the Saving Parameters (SP) bit. Default is 0 (i.e.
440 cleared). Equivalent to --sp in the main description.
441 -t outputs the temperature. Equivalent to --temperature in the main
443 description.
444 -T outputs the transport ('Protocol specific port') log page.
446 Equivalent to --transport in the main description.
447 -v increase level of verbosity.
449 -V print out version string then exit.
451 -x suppress the INQUIRY command. Equivalent to --no_inq in the main
453 description.
454 -? output usage message then exit.
456
458 Since sg3_utils version 1.23 the environment variable
459 SG3_UTILS_OLD_OPTS can be given. When it is present this utility will
460 expect the older command line options. So the presence of this environ‐
461 ment variable is equivalent to using --old (or -O) as the first command
462 line option.
463
465 Written by Douglas Gilbert
466
468 Report bugs to <dgilbert at interlog dot com>.
469
471 Copyright © 2002-2020 Douglas Gilbert
472 This software is distributed under the GPL version 2. There is NO war‐
473 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
474 POSE.
475
477 smartctl(smartmontools), sg_senddiag(8)
478sg3_utils-1.45 January 2020 SG_LOGS(8)