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 --se‐
30 lect option is given then a SCSI LOG SELECT command is issued to the
31 DEVICE. Alternatively one or more log page responses can be in a file
32 read using the --in=FN option; in this case those responses are decoded
33 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 op‐
62 tion 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 this utility's
87 internal tables about known log pages including their name,
88 acronym and fields. If given, the DEVICE argument is ignored.
89 When given once (e.g. '-e') all known pages are listed, sorted
90 in ascending alphabetical acronym order.
91 When given twice, vendor pages are excluded. When given three
92 times, all known pages are listed, sorted in ascending numeric
93 order listed; when given four times, vendor pages are excluded
94 from the numeric order.
95 The --filter=FL and --verbose options reduce the output of the
96 enumeration.
97 -f, --filter=FL
99 FL is either a parameter code when DEVICE is given, or a periph‐
100 eral device type (pdt) (or other) if --enumerate is given.
101 In the parameter code case FL is a value between 0 and 65535
102 (0xffff) and only the parameter section matching that code is
103 output. If the --hex option is given the log parameter is output
104 in hexadecimal rather than decoding it. If the --hex option is
105 used twice then the leading address on each line of hex is re‐
106 moved. If the --raw option is given then the log parameter is
107 output in binary. Most log pages contain one or more log parame‐
108 ters. Examples of those that don't follow that convention are
109 those pages that list supported log pages (and subpages).
110 In the --enumerate case, when FL >= zero it is taken as a pdt
111 value and only log pages associated with that pdt plus generic
112 pages listed in SPC are enumerated. If FL is -1 then the filter
113 does nothing which is the same as not giving this option; when
114 FL is -2 then only generic pages listed in SPC are enumerated.
115 If FL is -10 then only generic direct access like (e.g. disk)
116 pages are enumerated. If FL is -11 then only generic tape like
117 pages (e.g. includes ADC) are enumerated.
118 -h, --help
120 print out the usage message then exit.
121 -H, --hex
123 The default action is to decode known log page numbers (and sub‐
124 page numbers) into text. When this option is used once, the re‐
125 sponse is output in hexadecimal. When used twice, each line of
126 hex has the ASCII equivalent shown to the right. When used three
127 times, the hex has no leading address nor trailing ASCII making
128 it suitable to be placed in a file (or piped). That file might
129 later be used by another invocation using the --in=FN option.
130 -i, --in=FN
132 This option may be used in two different contexts. One is with
133 the --select to send a LOG SELECT command to the given DEVICE;
134 see the LOG SELECT section below.
135 The other context is with no DEVICE argument given in which case
136 the contents of FN are decoded as if it were the response of a
137 LOG SENSE command (i.e. a log page). For decoding the page and
138 subpage numbers are taken from FN while the peripheral device
139 type is either generic (i.e. from SPC) or the value given by
140 --pdt=DT.
141 FN is treated as a file name (or '-' for stdin) which contains
142 ASCII hexadecimal or binary representing a log page. The hexa‐
143 decimal should be arranged as 1 or 2 digits representing a byte
144 each of which is whitespace or comma separated. Anything from
145 and including a hash mark to the end of line is ignored. If the
146 --raw option is also given then FN is treated as binary.
147 -l, --list
149 lists the names of all logs sense pages supported by this de‐
150 vice. This is done by reading the "supported log pages" log
151 page. When used twice (e.g. '-ll') lists the names of all logs
152 sense pages and subpages supported by this device, excluding
153 pages whose subpage number is 0xff (apart from page 0x0,0xff).
154 When used three times then all supported pages and subpages re‐
155 ported by the device are list. So the page/subpage names and not
156 thrie content is shown with this option. There is a list of com‐
157 mon log page codes below.
158 -m, --maxlen=LEN
160 sets the "allocation length" field in the LOG SENSE cdb. The is
161 the maximum length in bytes that the response will be. Without
162 this option (or LEN equal to 0) this utility first fetches the 4
163 byte response then does a second access with the length indi‐
164 cated in the first (4 byte) response. Negative values and 1 for
165 LEN are not accepted. LEN cannot exceed 65535 (0xffff). Re‐
166 sponses can be quite large (e.g. the background scan results log
167 page) and this option can be used to limit the amount of infor‐
168 mation returned.
169 -n, --name
171 decode some log pages into 'name=value' entries, one per line.
172 The name contains no space and may be abbreviated and the value
173 is decimal unless prefixed by '0x'. Nesting is indicated by
174 leading spaces. This form is meant to be relatively easy to
175 parse.
176 -x, --no_inq
178 suppresses the output of information obtained from an initial
179 call to the INQUIRY command for the standard response. The de‐
180 fault (assuming some other options that suppress this output are
181 also not given) is to output several device identification
182 strings.
183 If this option is given twice (or more) then no INQUIRY command
184 is sent hence there will be no device identification string out‐
185 put either. Also the peripheral device type (PDT) field will not
186 be obtained so this utility will not be able to differentiate
187 between some log pages that are device dependent. It will assume
188 a PDT of 0 (i.e. a disk).
189 -O, --old
191 Switch to older style options. Please use as first option.
192 -p, --page=PG
194 log page name/number to access. PG is either an acronym, a page
195 number, or a page, subpage number pair. Available acronyms can
196 be listed with the --enumerate option. Page (0 to 63) and sub‐
197 page (0 to 255) numbers are comma separated. They are decimal
198 unless a hexadecimal indication is given. A hexadecimal number
199 can be specified by a leading "0x" or a trailing "h".
200 A few acronyms specify a range of subpage values in which case
201 the acronym may be followed by a comma then a subpage number.
202 This method can also be used to fetch the Supported subpages log
203 page (e.g. --page=temp,0xff).
204 -P, --paramp=PP
206 PP is the parameter pointer value to place in a field of that
207 name in the LOG SENSE cdb. A decimal number in the range 0 to
208 65535 (0xffff) is expected. When a value greater than 0 is given
209 the --ppc option should be selected. The default value is 0.
210 -q, --pcb
212 show Parameter Control Byte settings (only relevant when log pa‐
213 rameters being output in ASCII).
214 -Q, --ppc
216 sets the Parameter Pointer Control (PPC) bit in the LOG SENSE
217 cdb. Default is 0 (i.e. cleared). This bit was made obsolete in
218 SPC-4 revision 18.
219 -D, --pdt=DT
221 DT is the peripheral device type that is used when it is not
222 available from the DEVICE. There are two main cases of this:
223 with the --pdt=DT without a DEVICE and when --no_inq is used
224 with a DEVICE.
225 -r, --raw
227 output the response in binary to stdout. Error messages and
228 warnings are output to stderr.
229 This option may also be given together with --in=FN in which
230 case the contents of FN are interpreted as binary data (and the
231 response is decoded as normal, not dumped as binary).
232 -R, --readonly
234 open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
235 The default action is to try and open DEVICE read-write then if
236 that fails try to open again with read-only. However when a
237 read-write open succeeds there may still be unwanted actions on
238 the close (e.g. some OSes try to do a SYNCHRONIZE CACHE com‐
239 mand). So this option forces a read-only open on DEVICE and if
240 it fails, this utility will exit. Note that options like --se‐
241 lect most likely need a read-write open.
242 -R, --reset
244 use SCSI LOG SELECT command (with the PCR bit set) to reset the
245 all log pages (or the given page). Exactly what is reset depends
246 on the accompanying SP bit (i.e. --sp option which defaults to
247 0) and the PC ("page control") value (which defaults to 1). Sup‐
248 plying this option implies the --select option as well. This op‐
249 tion seems to clear error counter log pages but leaves pages
250 like self-test results, start-stop cycle counter and temperature
251 log pages unaffected. This option may be required to clear log
252 pages if a counter reaches its maximum value since the log page
253 in which the counter is found will remain "stuck" at its maximum
254 value until some user interaction (e.g. calling sg_logs with
255 this option).
256 -S, --select
258 use a LOG SELECT command. The default action (i.e. when neither
259 this option nor --reset is given) is to do a LOG SENSE command.
260 See the LOG SELECT section.
261 -s, --sp
263 sets the Saving Parameters (SP) bit. Default is 0 (i.e.
264 cleared). When set this instructs the device to store the cur‐
265 rent log page parameters (as indicated by the DS and TSD parame‐
266 ter codes) in some non-volatile location. Hence the log parame‐
267 ters will be preserved across power cycles. This option is typi‐
268 cally not needed, especially if the GLTSD flag is clear in the
269 control mode page as this instructs the device to periodically
270 save all saveable log parameters to non-volatile locations.
271 -t, --temperature
273 outputs the temperature. First looks in the temperature log page
274 and if that is not available tries the Informational Exceptions
275 log page which may also have the current temperature (especially
276 on older disks).
277 -T, --transport
279 outputs the transport ('Protocol specific port') log page.
280 Equivalent to setting '--page=18h'.
281 -M, --vendor=VP
283 where VP is a vendor/manufacturer (e.g. "sea" for Seagate) or
284 product (group) acronym (e.g. "lto5" for the 5th generation LTO
285 (tape) consortium). Either the whole log page is vendor specific
286 (e.g. page numbers 0x30 to 0x3f) or part of a T10 defined log
287 page is vendor specific. For example SPC-5 defines parameter
288 code 0x0 of page 0x2f (the Informational Exceptions log page)
289 and states that the remaining parameter codes (i.e. 0x1 to
290 0xffff) are vendor specific. Using a VP of "xxx" will list the
291 available acronyms.
292 If this option is used with --page=PG and PG is an acronym then
293 this option is ignored. If PG is a number (e.g. 0xc0) then VP is
294 used to choose the which vendor specific page (e.g. sharing page
295 number 0xc0) to decode.
296 -v, --verbose
298 increase level of verbosity. When used with --enumerate, in the
299 list of known log page names, those that have no associated de‐
300 code logic are followed by "[hex only]".
301 -V, --version
303 print out version string then exit.
304
306 The SCSI LOG SELECT command can be used to reset certain parameters to
307 vendor specific defaults, save them to non-volatile storage (i.e. the
308 media), or supply new page contents. This command has changed between
309 SPC-3 and SPC-4 with the addition of the Page and Subpage Code fields
310 which can only be non zero when the Parameter list length is zero.
311 The --select (or --reset) option is required to issue a LOG SELECT com‐
313 mand. If the --in=FN option is not given (or FN is effectively empty)
314 then the Parameter list length field is set to zero. If the --in=FN op‐
315 tion is is given then its decoded data is placed in the data-out buffer
316 and its length in bytes is placed in the Parameter list length 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 re‐
340 sponse it can calculate the actual length of the response which is what
341 it asks for on the second fetch. This is typical practice in SCSI and
342 guaranteed to work in the standards. However some older devices don't
343 comply. For those devices using the --maxlen=LEN option will do a sin‐
344 gle 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 de‐
395 vice. 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 de‐
399 scription.
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 pa‐
424 rameters 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 de‐
431 scription.
432 -R Equivalent to --readonly in the main description.
434 -select
436 use a LOG SELECT command. Equivalent to --select in the main de‐
437 scription.
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)