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

NAME

6       sg_logs - access log pages with SCSI LOG SENSE command
7

SYNOPSIS

9       sg_logs   [--All]   [--all]   [--brief]   [--control=PC]  [--enumerate]
10       [--enum_vendor]  [--filter=FL]  [--help]  [--hex]  [--in=FN]   [--list]
11       [--maxlen=LEN]  [--name]  [--no_inq]  [--page=PG] [--paramp=PP] [--pcb]
12       [--ppc] [--raw] [--readonly] [--reset]  [--select]  [--sp]  [--tempera‐
13       ture] [--transport] [--verbose] [--version] DEVICE
14
15       sg_logs [-a] [-A] [-b] [-c=PC] [-e] [-E] [-f=FL] [-h] [-H] [-i=FN] [-l]
16       [-L]  [-m=LEN]  [-n]  [-p=PG]  [-paramp=PP]  [-pcb]  [-ppc]  [-r]  [-R]
17       [-select] [-sp] [-t] [-T] [-v] [-V] [-?]  [-x] DEVICE
18

DESCRIPTION

20       This utility sends a SCSI LOG SENSE command to the DEVICE and then out‐
21       puts the response. The LOG SENSE command is used to  fetch  log  pages.
22       Known log pages can be decoded. When the --reset and/or --select option
23       is given then a SCSI LOG SELECT command is issued.
24
25       In SPC-4 revision 5 a subpage code was introduced to both the LOG SENSE
26       and  LOG  SELECT command. At the same time a page code field was intro‐
27       duced to the to the LOG SELECT command. The log subpage code can  range
28       from  0  to  255  (0xff)  inclusive.  The subpage code value 255 can be
29       thought of as a wildcard.
30
31       This utility supports two command line syntaxes, the preferred  one  is
32       shown first in the synopsis and explained in this section. A later sec‐
33       tion on the old command  line  syntax  outlines  the  second  group  of
34       options.
35

OPTIONS

37       Arguments to long options are mandatory for short options as well.
38
39       -A, --All
40              fetch and decode all the log pages and subpages supported by the
41              DEVICE.  This requires a two stage process: first the "supported
42              log pages and subpages" log page is fetched, then for each entry
43              in the response, the corresponding  log  page  (or  subpage)  is
44              fetched  and  displayed.  Note  that there are many SCSI devices
45              that do not support LOG  SENSE  subpages  and  respond  to  this
46              option with an illegal request sense key.
47
48       -a, --all
49              outputs all the log pages supported by the DEVICE. This requires
50              a two stage process: first the "supported log pages" log page is
51              fetched,  then for each entry in the response, the corresponding
52              log page is fetched and displayed. When used twice (e.g.  '-aa')
53              all log pages and subpages are fetched.
54
55       -b, --brief
56              shorten the amount of output for some log pages. For example the
57              Tape Alert log page only outputs parameters whose flags are  set
58              when --brief is given.
59
60       -c, --control=PC
61              accepts 0, 1, 2 or 3 for the PC argument:
62                0 : current threshold values
63                1 : current cumulative values
64                2 : default threshold values
65                3 : default cumulative values
66              The default value is 1 (i.e. current cumulative values).
67
68       -e, --enumerate
69              this  option  is  used  to  output  information held in internal
70              tables about known log pages including their names and acronyms.
71              If  given  DEVICE  is  ignored.  When given once (e.g. '-e') all
72              known pages are listed, sorted in ascending acronym order.  When
73              given twice, vendor pages are excluded.  When given three times,
74              all known pages are listed, sorted in  ascending  numeric  order
75              listed;  when  given  four times, vendor pages are excluded from
76              the numeric order.
77              The --filter=FL and --verbose options modify the output  of  the
78              enumeration.
79
80       -E, --enum_vendor
81              this  option  is  used  to  output  information held in internal
82              tables about known vendor specific  log  pages  including  their
83              names and acronyms.
84
85       -f, --filter=FL
86              FL is either a parameter code when DEVICE is given, or a periph‐
87              eral device type (pdt) (or other) if --enumerate is given.
88              In the parameter code case FL is a value  between  0  and  65535
89              (0xffff)  and  only  the parameter section matching that code is
90              output.  The --hex option outputs log parameter  in  hexadecimal
91              rather  than decoding it. If the --hex option is used twice then
92              the leading address on each line of hex is removed. If the --raw
93              option  is  given  then  the  log parameter is output in binary.
94              Most log pages contain one or more log parameters.  Examples  of
95              those that don't are those pages that list supported log pages.
96              In  the  --enumerate  case, when FL >= zero it is taken as a pdt
97              value and only log pages associated with that pdt  plus  generic
98              pages  listed in SPC are enumerated. If FL is -1 then the filter
99              does nothing which is the same as not giving this  option;  when
100              FL  is  -2 then only generic pages listed in SPC are enumerated.
101              If FL is -10 then only generic direct access  like  (e.g.  disk)
102              pages  are  enumerated. If FL is -11 then only generic tape like
103              pages (e.g. includes ADC) are enumerated.
104
105       -h, --help
106              print out the usage message then exit.
107
108       -H, --hex
109              The default action is to decode known  mode  page  numbers  (and
110              subpage  numbers)  into text. When this option is used once, the
111              response is output in hexadecimal. When used twice, each line of
112              hex has the ASCII equivalent shown to the right. When used three
113              times, the hex has no leading address nor trailing ASCII  making
114              it  suitable  to be placed in a file (or piped). That file might
115              later be used by another invocation using the --in=FN option.
116
117       -i, --in=FN
118              This option may be used in two different contexts. One  is  with
119              the  --select  to send a LOG SELECT command to the given DEVICE;
120              see the LOG SELECT section below.
121              The other context is with no DEVICE argument given in which case
122              the  contents  of FN are decoded as if it were the response of a
123              LOG SENSE command (i.e. a log page). For decoding the  page  and
124              subpage  numbers  are  taken  from  FN  while the device type is
125              either generic (i.e. from SPC) or  the  value  given  by  --fil‐
126              ter=FL.
127              FN  is  treated as a file name (or '-' for stdin) which contains
128              ASCII hexadecimal or binary representing a log page.  The  hexa‐
129              decimal  should be arranged as 1 or 2 digits representing a byte
130              each of which is whitespace or comma  separated.  Anything  from
131              and  including a hash mark to the end of line is ignored. If the
132              --raw option is also given then FN is treated as binary.
133
134       -l, --list
135              lists the names of  all  logs  sense  pages  supported  by  this
136              device.  This  is  done by reading the "supported log pages" log
137              page. When used twice (e.g. '-ll') lists the names of  all  logs
138              sense  pages  and  subpages supported by this device. There is a
139              list of common log page codes below.
140
141       -m, --maxlen=LEN
142              sets the "allocation length" field in the LOG SENSE cdb. The  is
143              the  maximum  length in bytes that the response will be. Without
144              this option (or LEN equal to 0) this utility first fetches the 4
145              byte  response  then  does a second access with the length indi‐
146              cated in the first (4 byte) response. Negative values and 1  for
147              LEN   are  not  accepted.  LEN  cannot  exceed  65535  (0xffff).
148              Responses can be quite large (e.g. the background  scan  results
149              log  page)  and  this  option can be used to limit the amount of
150              information returned.
151
152       -n, --name
153              decode some log pages into 'name=value' entries, one  per  line.
154              The  name contains no space and may be abbreviated and the value
155              is decimal unless prefixed by  '0x'.  Nesting  is  indicated  by
156              leading  spaces.  This  form  is  meant to be relatively easy to
157              parse.
158
159       -x, --no_inq
160              suppresses the output of information obtained  from  an  initial
161              call  to  the  INQUIRY  command  for  the standard response. The
162              default (assuming some other options that suppress  this  output
163              are  also  not given) is to output several device identification
164              strings.
165              If this option is given twice (or more) then no INQUIRY  command
166              is sent hence there will be no device identification string out‐
167              put either. Also the peripheral device type (PDT) field will not
168              be  obtained  so  this utility will not be able to differentiate
169              between some log pages that are device dependent. It will assume
170              a PDT of 0 (i.e. a disk).
171
172       -O, --old
173              switch to older style options.
174
175       -p, --page=PG
176              log  page name/number to access. PG is either an acronym, a page
177              number, or a page, subpage number pair. Available  acronyms  can
178              be  listed  with the --enumerate option. Page (0 to 63) and sub‐
179              page (0 to 255) numbers are comma separated.  They  are  decimal
180              unless  a  hexadecimal indication is given. A hexadecimal number
181              can be specified by a leading "0x" or a trailing "h".
182              A few acronyms specify a range of subpage values in  which  case
183              the  acronym  may  be followed by a comma then a subpage number.
184              This method can also be used to fetch the Supported subpages log
185              page (e.g. --page=temp,0xff).
186
187       -P, --paramp=PP
188              PP  is  the  parameter pointer value to place in a field of that
189              name in the LOG SENSE cdb. A decimal number in the  range  0  to
190              65535 (0xffff) is expected. When a value greater than 0 is given
191              the --ppc option should be selected. The default value is 0.
192
193       -q, --pcb
194              show Parameter Control Byte settings  (only  relevant  when  log
195              parameters being output in ASCII).
196
197       -Q, --ppc
198              sets  the  Parameter  Pointer Control (PPC) bit in the LOG SENSE
199              cdb. Default is 0 (i.e. cleared). This bit was made obsolete  in
200              SPC-4 revision 18.
201
202       -r, --raw
203              output  the  response  in  binary  to stdout. Error messages and
204              warnings are output to stderr.
205
206       -R, --readonly
207              open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
208              The  default action is to try and open DEVICE read-write then if
209              that fails try to open again  with  read-only.  However  when  a
210              read-write  open succeeds there may still be unwanted actions on
211              the close (e.g. some OSes try to do  a  SYNCHRONIZE  CACHE  com‐
212              mand).  So  this option forces a read-only open on DEVICE and if
213              it fails,  this  utility  will  exit.  Note  that  options  like
214              --select most likely need a read-write open.
215
216       -R, --reset
217              use  SCSI  LOG SELECT command (PCR bit set) to reset the all log
218              pages (or the given page). Exactly what is reset depends on  the
219              accompanying  SP  bit (i.e. --sp option which defaults to 0) and
220              the PC ("page control") value (which defaults to  1).  Supplying
221              this  option  implies  the  --select option as well. This option
222              seems to clear error counter log pages  but  leaves  pages  like
223              self-test  results, start-stop cycle counter and temperature log
224              pages unaffected. This option may be required to clear log pages
225              if  a  counter  reaches  its maximum value since the log page in
226              which the counter is found will remain "stuck"  until  something
227              is done.
228
229       -S, --select
230              use  a LOG SELECT command. The default action (i.e. when neither
231              this option nor --reset is given) is to do a LOG SENSE  command.
232              See the LOG SELECT section.
233
234       -s, --sp
235              sets  the  Saving  Parameters  (SP)  bit.  Default  is  0  (i.e.
236              cleared). When set this instructs the device to store  the  cur‐
237              rent log page parameters (as indicated by the DS and TSD parame‐
238              ter codes) in some non-volatile location.  Hence the log parame‐
239              ters will be preserved across power cycles. This option is typi‐
240              cally not needed, especially if the GLTSD flag is clear  in  the
241              control  mode  page as this instructs the device to periodically
242              save all saveable log parameters to non-volatile locations.
243
244       -t, --temperature
245              outputs the temperature. First looks in the temperature log page
246              and  if that is not available tries the Informational Exceptions
247              log page which may also have the current temperature (especially
248              on older disks).
249
250       -T, --transport
251              outputs  the  transport  ('Protocol  specific  port')  log page.
252              Equivalent to setting '--page=18h'.
253
254       -v, --verbose
255              increase level of verbosity. When used with --enumerate, in  the
256              list  of  known  log  page  names, those that have no associated
257              decode logic are followed by "[hex only]".
258
259       -V, --version
260              print out version string then exit.
261

LOG SELECT

263       The LOG SELECT command can be used to reset certain parameters to  ven‐
264       dor  specific  defaults,  save  them  to non-volatile storage (i.e. the
265       media), or supply new page contents. This command has  changed  between
266       SPC-3  and  SPC-4 with the addition of the Page and Subpage Code fields
267       which can only be non zero when the Parameter list length is zero.
268
269       The --select option is required to issue a LOG SELECT command.  If  the
270       --in=FN  option  is  not  given  (or  FN is effectively empty) then the
271       Parameter list length field is set to zero. If the --in=FN option is is
272       given  then  its  decoded data is placed in the data-out buffer and its
273       length in bytes is placed in the Parameter list length field.
274
275       Other options that are active with the LOG SELECT  command  are  --con‐
276       trol=PC, --reset (which sets the PCR bit) and --sp.
277

APPLICATION CLIENT

279       This  is  the name of a log page that acts as a container for data pro‐
280       vided by the user. An application client is a SCSI term for the program
281       that  issues  commands  to  a SCSI initiator (often known as a Host Bus
282       Adapter (HBA)). So, for example, this utility  is  a  SCSI  application
283       client.
284
285       The  Application  Client log page has 64 log parameters with parameters
286       codes 0 to 63. Each can hold 252 bytes of user binary  data.  That  252
287       bytes  (or less) of user data, with a 4 byte prefix (for a total of 256
288       bytes) can be provided with the --in=FN option. A typical prefix  would
289       be  '0,n,83,fc'.  The  "n" is the parameter code in hex so the last log
290       parameter would be '0,3f,83,fc'. That log parameter could be read  back
291       at some later time with '--page=0xf --filter=0x<n>'.
292

NOTES

294       This  utility will usually do a double fetch of log pages with the SCSI
295       LOG SENSE command. The first fetch requests a  4  byte  response  (i.e.
296       place  4  in  the  "allocation  length"  field  in  the cdb). From that
297       response it can calculate the actual length of the  response  which  is
298       what  it asks for on the second fetch. This is typical practice in SCSI
299       and guaranteed to work in the standards.  However  some  older  devices
300       don't comply. For those devices using the --maxlen=LEN option will do a
301       single fetch.  A value of 252 should be a safe starting point.
302
303       Various log pages hold information  error  rates,  device  temperature,
304       start  stop cycles since device produced and the results of the last 20
305       self tests. Self tests can be initiated by the sg_senddiag(8)  utility.
306       The  smartmontools  package provides much of the information found with
307       sg_logs in a form suitable for monitoring the health of SCSI disks  and
308       tape drives.
309
310       The simplest way to find which log pages can be decoded by this utility
311       is to use the --enumerate option. Some page names are known  but  there
312       is  no  decode  logic;  such cases have "[hex only]" after the log page
313       name when the --verbose option is given with --enumerate.
314

EXIT STATUS

316       The exit status of sg_logs is 0 when it is  successful.  Otherwise  see
317       the sg3_utils(8) man page.
318

OLDER COMMAND LINE OPTIONS

320       The  options  in  this  section  were  the only ones available prior to
321       sg3_utils version 1.23 . In sg3_utils  version  1.23  and  later  these
322       older  options can be selected by either setting the SG3_UTILS_OLD_OPTS
323       environment variable or using '--old' (or '-O) as the first option.
324
325       Options with arguments or with two or more letters can  have  an  extra
326       '-' prepended. For example: both '-pcb' and '--pcb' are acceptable.
327
328       -a     outputs  all  the log pages supported by the device.  Equivalent
329              to --all in the main description.
330
331       -A     outputs all the log pages and subpages supported by the  device.
332              Equivalent to '--all --all' in the main description.
333
334       -c=PC  Equivalent to --control=PC in the main description.
335
336       -e     enumerate  internal  tables  to show information about known log
337              pages.  Equivalent to --enumerate in the main description.
338
339       -E     enumerate internal tables to show information about known vendor
340              specific  log  pages.  Equivalent  to  --enum_vendor in the main
341              description.
342
343       -h     suppresses decoding of known log sense pages and prints out  the
344              response in hex instead.
345
346       -i=FN  FN  is  treated as a file name (or '-' for stdin) which contains
347              ASCII hexadecimal representing a log page that will be  sent  as
348              parameter  data of a LOG SELECT command. See the LOG SELECT sec‐
349              tion.
350
351       -H     same action as '-h' in this section and equivalent to  --hex  in
352              the main description.
353
354       -l     lists  the  names  of  all  logs  sense  pages supported by this
355              device.  Equivalent to --list in the main description.
356
357       -L     lists the names of all logs sense pages and  subpages  supported
358              by  this  device.  Equivalent  to  '--list  --list'  in the main
359              description.
360
361       -m=LEN request only LEN bytes of response data. Default is 0  which  is
362              interpreted  as  all that is available. LEN is decimal unless it
363              has a leading '0x' or trailing 'h'.  Equivalent to  --maxlen=LEN
364              in the main description.
365
366       -n     Equivalent to --name in the main description.
367
368       -N     switch to the newer style options.
369
370       -p=PG  log page code to access. PG is either an acronym, a page number,
371              or a page, subpage pair. Available acronyms can be  listed  with
372              the  --enumerate  option.  Page  (0 to 3f) and subpage (0 to ff)
373              numbers are comma separated. The numbers are assumed to be hexa‐
374              decimal.
375
376       -paramp=PP
377              PP  is the parameter pointer value (in hex) to place in command.
378              Should be a number between 0 and ffff inclusive.
379
380       -pcb   show Parameter Control Byte settings  (only  relevant  when  log
381              parameters being output in ASCII).
382
383       -ppc   sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e.
384              cleared).
385
386       -r     use SCSI LOG SELECT command (PCR bit set) to reset the  all  log
387              pages  (or  the  given  page). Equivalent to --reset in the main
388              description.
389
390       -R     Equivalent to --readonly in the main description.
391
392       -select
393              use a LOG SELECT command. Equivalent to  --select  in  the  main
394              description.
395
396       -sp    sets  the  Saving  Parameters  (SP)  bit.  Default  is  0  (i.e.
397              cleared).  Equivalent to --sp in the main description.
398
399       -t     outputs the temperature. Equivalent to --temperature in the main
400              description.
401
402       -T     outputs  the  transport  ('Protocol  specific  port')  log page.
403              Equivalent to --transport in the main description.
404
405       -v     increase level of verbosity.
406
407       -V     print out version string then exit.
408
409       -x     suppress the INQUIRY command. Equivalent to --no_inq in the main
410              description.
411
412       -?     output usage message then exit.
413

AUTHOR

415       Written by Douglas Gilbert
416

REPORTING BUGS

418       Report bugs to <dgilbert at interlog dot com>.
419
421       Copyright © 2002-2016 Douglas Gilbert
422       This  software is distributed under the GPL version 2. There is NO war‐
423       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
424       POSE.
425

SEE ALSO

427       smartctl(smartmontools), sg_senddiag(8)
428
429
430
431sg3_utils-1.42                   February 2016                      SG_LOGS(8)
Impressum