sg_logs - access log pages with SCSI LOG SENSE command
sg_logs [--All] [--all] [--brief] [--filter=FL] [--hex] [--list] [--maxlen=LEN] [--name] [--no_inq] [--page=PG] [--paramp=PP] [--pcb] [--ppc] [--pdt=DT] [--raw] [--readonly] [--sp] [--temperature] [--transport] [--vendor=VP] [--verbose] DEVICE sg_logs [--brief] [--filter=FL] [--hex] --in=FN [--name] [--pdt=DT] [--raw] [--vendor=VP] sg_logs [--control=PC] [--in=FN] [--page=PG] [--raw] [--reset] --select [--sp] [--verbose] DEVICE sg_logs [--enumerate] [--filter=FL] [--help] [--vendor=VP] [--version] sg_logs [-a] [-A] [-b] [-D=DT] [-c=PC] [-e] [-f=FL] [-h] [-H] [-i=FN] [-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb] [-ppc] [-r] [-R] [-select] [-sp] [-t] [-T] [-v] [-V] [-?] [-x] DEVICE
SG_LOGS(8) SG3_UTILS SG_LOGS(8)
NAME
sg_logs - access log pages with SCSI LOG SENSE command
SYNOPSIS
sg_logs [--All] [--all] [--brief] [--filter=FL] [--hex] [--list]
[--maxlen=LEN] [--name] [--no_inq] [--page=PG] [--paramp=PP] [--pcb]
[--ppc] [--pdt=DT] [--raw] [--readonly] [--sp] [--temperature]
[--transport] [--vendor=VP] [--verbose] DEVICE
sg_logs [--brief] [--filter=FL] [--hex] --in=FN [--name] [--pdt=DT]
[--raw] [--vendor=VP]
sg_logs [--control=PC] [--in=FN] [--page=PG] [--raw] [--reset] --select
[--sp] [--verbose] DEVICE
sg_logs [--enumerate] [--filter=FL] [--help] [--vendor=VP] [--version]
sg_logs [-a] [-A] [-b] [-D=DT] [-c=PC] [-e] [-f=FL] [-h] [-H] [-i=FN]
[-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb] [-ppc] [-r]
[-R] [-select] [-sp] [-t] [-T] [-v] [-V] [-?] [-x] DEVICE
DESCRIPTION
This utility sends a SCSI LOG SENSE command to the DEVICE and then out-
puts the response. The LOG SENSE command is used to fetch log pages
which, if known, are decoded by default. When the --reset and/or
--select option is given then a SCSI LOG SELECT command is issued to
the DEVICE. Alternatively one or more log page responses can be in a
file read using the --in=FN option; in this case those responses are
decoded and the DEVICE argument, if given, is ignored.
In SPC-4 revision 5 a subpage code was introduced to both the LOG SENSE
and LOG SELECT command. At the same time a page code field was intro-
duced to the to the LOG SELECT command. The log subpage code can range
from 0 to 255 (0xff) inclusive. The subpage code value 255 can be
thought of as a wildcard.
The SYNOPSIS section above is divided into five forms. The first form
shows the options that can be used to send a LOG SENSE command to the
DEVICE and decode its response. The second form fetches data from a
file (named FN) and decodes it as if it were a response from a LOG
SENSE command. The third form shows the options that can be used to
send a LOG SELECT command. The fourth form groups various management
options. The last form shows the older, deprecated command line inter-
face which is maintained for backward compatibility.
OPTIONS
Arguments to long options are mandatory for short options as well. The
options are arranged in alphabetical order based on the long option
name.
-A, --All
fetch and decode all the log pages and subpages supported by the
DEVICE. This requires a two stage process: first the "supported
log pages and subpages" log page is fetched, then for each entry
in its response, the corresponding log page (or subpage) is
fetched and displayed. Note that there are many SCSI devices
that do not support LOG SENSE subpages and respond to this
option with an illegal request sense key (or ignored the subpage
field).
-a, --all
outputs all the log pages supported by the DEVICE. This requires
a two stage process: first the "supported log pages" log page is
fetched, then for each entry in its response, the corresponding
log page is fetched and displayed. When used twice (e.g. '-aa')
all log pages and subpages are fetched.
-b, --brief
shorten the amount of output for some log pages. For example the
Tape Alert log page only outputs parameters whose flags are set
when --brief is given.
-c, --control=PC
accepts 0, 1, 2 or 3 for the PC argument:
0 : current threshold values
1 : current cumulative values
2 : default threshold values
3 : default cumulative values
The default value is 1 (i.e. current cumulative values).
-e, --enumerate
this option is used to output information held in this utility's
internal tables about known log pages including their name,
acronym and fields. If given, the DEVICE argument is ignored.
When given once (e.g. '-e') all known pages are listed, sorted
in ascending alphabetical acronym order.
When given twice, vendor pages are excluded. When given three
times, all known pages are listed, sorted in ascending numeric
order listed; when given four times, vendor pages are excluded
from the numeric order.
The --filter=FL and --verbose options reduce the output of the
enumeration.
-f, --filter=FL
FL is either a parameter code when DEVICE is given, or a periph-
eral device type (pdt) (or other) if --enumerate is given.
In the parameter code case FL is a value between 0 and 65535
(0xffff) and only the parameter section matching that code is
output. If the --hex option is given the log parameter is output
in hexadecimal rather than decoding it. If the --hex option is
used twice then the leading address on each line of hex is
removed. If the --raw option is given then the log parameter is
output in binary. Most log pages contain one or more log parame-
ters. Examples of those that don't follow that convention are
those pages that list supported log pages (and subpages).
In the --enumerate case, when FL >= zero it is taken as a pdt
value and only log pages associated with that pdt plus generic
pages listed in SPC are enumerated. If FL is -1 then the filter
does nothing which is the same as not giving this option; when
FL is -2 then only generic pages listed in SPC are enumerated.
If FL is -10 then only generic direct access like (e.g. disk)
pages are enumerated. If FL is -11 then only generic tape like
pages (e.g. includes ADC) are enumerated.
-h, --help
print out the usage message then exit.
-H, --hex
The default action is to decode known log page numbers (and sub-
page numbers) into text. When this option is used once, the
response is output in hexadecimal. When used twice, each line of
hex has the ASCII equivalent shown to the right. When used three
times, the hex has no leading address nor trailing ASCII making
it suitable to be placed in a file (or piped). That file might
later be used by another invocation using the --in=FN option.
-i, --in=FN
This option may be used in two different contexts. One is with
the --select to send a LOG SELECT command to the given DEVICE;
see the LOG SELECT section below.
The other context is with no DEVICE argument given in which case
the contents of FN are decoded as if it were the response of a
LOG SENSE command (i.e. a log page). For decoding the page and
subpage numbers are taken from FN while the peripheral device
type is either generic (i.e. from SPC) or the value given by
--pdt=DT.
FN is treated as a file name (or '-' for stdin) which contains
ASCII hexadecimal or binary representing a log page. The hexa-
decimal should be arranged as 1 or 2 digits representing a byte
each of which is whitespace or comma separated. Anything from
and including a hash mark to the end of line is ignored. If the
--raw option is also given then FN is treated as binary.
-l, --list
lists the names of all logs sense pages supported by this
device. This is done by reading the "supported log pages" log
page. When used twice (e.g. '-ll') lists the names of all logs
sense pages and subpages supported by this device, excluding
pages whose subpage number is 0xff (apart from page 0x0,0xff).
When used three times then all supported pages and subpages
reported by the device are list. So the page/subpage names and
not thrie content is shown with this option. There is a list of
common log page codes below.
-m, --maxlen=LEN
sets the "allocation length" field in the LOG SENSE cdb. The is
the maximum length in bytes that the response will be. Without
this option (or LEN equal to 0) this utility first fetches the 4
byte response then does a second access with the length indi-
cated in the first (4 byte) response. Negative values and 1 for
LEN are not accepted. LEN cannot exceed 65535 (0xffff).
Responses can be quite large (e.g. the background scan results
log page) and this option can be used to limit the amount of
information returned.
-n, --name
decode some log pages into 'name=value' entries, one per line.
The name contains no space and may be abbreviated and the value
is decimal unless prefixed by '0x'. Nesting is indicated by
leading spaces. This form is meant to be relatively easy to
parse.
-x, --no_inq
suppresses the output of information obtained from an initial
call to the INQUIRY command for the standard response. The
default (assuming some other options that suppress this output
are also not given) is to output several device identification
strings.
If this option is given twice (or more) then no INQUIRY command
is sent hence there will be no device identification string out-
put either. Also the peripheral device type (PDT) field will not
be obtained so this utility will not be able to differentiate
between some log pages that are device dependent. It will assume
a PDT of 0 (i.e. a disk).
-O, --old
Switch to older style options. Please use as first option.
-p, --page=PG
log page name/number to access. PG is either an acronym, a page
number, or a page, subpage number pair. Available acronyms can
be listed with the --enumerate option. Page (0 to 63) and sub-
page (0 to 255) numbers are comma separated. They are decimal
unless a hexadecimal indication is given. A hexadecimal number
can be specified by a leading "0x" or a trailing "h".
A few acronyms specify a range of subpage values in which case
the acronym may be followed by a comma then a subpage number.
This method can also be used to fetch the Supported subpages log
page (e.g. --page=temp,0xff).
-P, --paramp=PP
PP is the parameter pointer value to place in a field of that
name in the LOG SENSE cdb. A decimal number in the range 0 to
65535 (0xffff) is expected. When a value greater than 0 is given
the --ppc option should be selected. The default value is 0.
-q, --pcb
show Parameter Control Byte settings (only relevant when log
parameters being output in ASCII).
-Q, --ppc
sets the Parameter Pointer Control (PPC) bit in the LOG SENSE
cdb. Default is 0 (i.e. cleared). This bit was made obsolete in
SPC-4 revision 18.
-D, --pdt=DT
DT is the peripheral device type that is used when it is not
available from the DEVICE. There are two main cases of this:
with the --pdt=DT without a DEVICE and when --no_inq is used
with a DEVICE.
-r, --raw
output the response in binary to stdout. Error messages and
warnings are output to stderr.
This option may also be given together with --in=FN in which
case the contents of FN are interpreted as binary data (and the
response is decoded as normal, not dumped as binary).
-R, --readonly
open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag).
The default action is to try and open DEVICE read-write then if
that fails try to open again with read-only. However when a
read-write open succeeds there may still be unwanted actions on
the close (e.g. some OSes try to do a SYNCHRONIZE CACHE com-
mand). So this option forces a read-only open on DEVICE and if
it fails, this utility will exit. Note that options like
--select most likely need a read-write open.
-R, --reset
use SCSI LOG SELECT command (with the PCR bit set) to reset the
all log pages (or the given page). Exactly what is reset depends
on the accompanying SP bit (i.e. --sp option which defaults to
0) and the PC ("page control") value (which defaults to 1). Sup-
plying this option implies the --select option as well. This
option seems to clear error counter log pages but leaves pages
like self-test results, start-stop cycle counter and temperature
log pages unaffected. This option may be required to clear log
pages if a counter reaches its maximum value since the log page
in which the counter is found will remain "stuck" at its maximum
value until some user interaction (e.g. calling sg_logs with
this option).
-S, --select
use a LOG SELECT command. The default action (i.e. when neither
this option nor --reset is given) is to do a LOG SENSE command.
See the LOG SELECT section.
-s, --sp
sets the Saving Parameters (SP) bit. Default is 0 (i.e.
cleared). When set this instructs the device to store the cur-
rent log page parameters (as indicated by the DS and TSD parame-
ter codes) in some non-volatile location. Hence the log parame-
ters will be preserved across power cycles. This option is typi-
cally not needed, especially if the GLTSD flag is clear in the
control mode page as this instructs the device to periodically
save all saveable log parameters to non-volatile locations.
-t, --temperature
outputs the temperature. First looks in the temperature log page
and if that is not available tries the Informational Exceptions
log page which may also have the current temperature (especially
on older disks).
-T, --transport
outputs the transport ('Protocol specific port') log page.
Equivalent to setting '--page=18h'.
-M, --vendor=VP
where VP is a vendor/manufacturer (e.g. "sea" for Seagate) or
product (group) acronym (e.g. "lto5" for the 5th generation LTO
(tape) consortium). Either the whole log page is vendor specific
(e.g. page numbers 0x30 to 0x3f) or part of a T10 defined log
page is vendor specific. For example SPC-5 defines parameter
code 0x0 of page 0x2f (the Informational Exceptions log page)
and states that the remaining parameter codes (i.e. 0x1 to
0xffff) are vendor specific. Using a VP of "xxx" will list the
available acronyms.
If this option is used with --page=PG and PG is an acronym then
this option is ignored. If PG is a number (e.g. 0xc0) then VP is
used to choose the which vendor specific page (e.g. sharing page
number 0xc0) to decode.
-v, --verbose
increase level of verbosity. When used with --enumerate, in the
list of known log page names, those that have no associated
decode logic are followed by "[hex only]".
-V, --version
print out version string then exit.
LOG SELECT
The SCSI LOG SELECT command can be used to reset certain parameters to
vendor specific defaults, save them to non-volatile storage (i.e. the
media), or supply new page contents. This command has changed between
SPC-3 and SPC-4 with the addition of the Page and Subpage Code fields
which can only be non zero when the Parameter list length is zero.
The --select (or --reset) option is required to issue a LOG SELECT com-
mand. If the --in=FN option is not given (or FN is effectively empty)
then the Parameter list length field is set to zero. If the --in=FN
option is is given then its decoded data is placed in the data-out buf-
fer and its length in bytes is placed in the Parameter list length
field.
Other options that are active with the LOG SELECT command are --con-
trol=PC, --reset (which sets the PCR bit) and --sp.
APPLICATION CLIENT
This is the name of a log page that acts as a container for data pro-
vided by the user. An application client is a SCSI term for the program
that issues commands to a SCSI initiator (often known as a Host Bus
Adapter (HBA)). So, for example, this utility is a SCSI application
client.
The Application Client log page has 64 log parameters with parameters
codes 0 to 63. Each can hold 252 bytes of user binary data. That 252
bytes (or less) of user data, with a 4 byte prefix (for a total of 256
bytes) can be provided with the --in=FN option. A typical prefix would
be '0,n,83,fc'. The "n" is the parameter code in hex so the last log
parameter would be '0,3f,83,fc'. That log parameter could be read back
at some later time with '--page=0xf --filter=0x<n>'.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+--------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+--------------------------+
|Availability | system/storage/sg3_utils |
+---------------+--------------------------+
|Stability | Pass-through uncommitted |
+---------------+--------------------------+
NOTES
This utility will usually do a double fetch of log pages with the SCSI
LOG SENSE command. The first fetch requests a 4 byte response (i.e.
place 4 in the "allocation length" field in the cdb). From that
response it can calculate the actual length of the response which is
what it asks for on the second fetch. This is typical practice in SCSI
and guaranteed to work in the standards. However some older devices
don't comply. For those devices using the --maxlen=LEN option will do a
single fetch. A value of 252 should be a safe starting point.
Various log pages hold information error rates, device temperature,
start stop cycles since the device was produced and the results of the
last 20 self tests. Self tests can be initiated by the sg_senddiag(8)
utility. The smartmontools package provides much of the information
found with sg_logs in a form suitable for monitoring the health of SCSI
disks and tape drives.
The simplest way to find which log pages can be decoded by this utility
is to use the --enumerate option. Some page names are known but there
is no decode logic; such cases have "[hex only]" after the log page
name when the --verbose option is given with --enumerate.
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://sg.danny.cz/sg/p/sg3_utils-1.46.tgz.
Further information about this software can be found on the open source
community website at http://sg.danny.cz/sg/sg3_utils.html.
EXIT STATUS
The exit status of sg_logs is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
OLDER COMMAND LINE OPTIONS
The options in this section were the only ones available prior to
sg3_utils version 1.23 . Since then this utility defaults to the newer
command line options which can be overridden by using --old (or -O) as
the first option. See the ENVIRONMENT VARIABLES section for another way
to force the use of these older command line options.
Options with arguments or with two or more letters can have an extra
'-' prepended. For example: both '-pcb' and '--pcb' are acceptable.
-a outputs all the log pages supported by the device. Equivalent
to --all in the main description.
-A outputs all the log pages and subpages supported by the device.
Equivalent to '--all --all' in the main description.
-c=PC Equivalent to --control=PC in the main description.
-e enumerate internal tables to show information about known log
pages. Equivalent to --enumerate in the main description.
-h suppresses decoding of known log sense pages and prints out the
response in hex instead.
-i=FN FN is treated as a file name (or '-' for stdin) which contains
ASCII hexadecimal representing a log page that will be sent as
parameter data of a LOG SELECT command. See the LOG SELECT sec-
tion.
-H same action as '-h' in this section and equivalent to --hex in
the main description.
-l lists the names of all logs sense pages supported by this
device. Equivalent to --list in the main description.
-L lists the names of all logs sense pages and subpages supported
by this device. Equivalent to '--list --list' in the main
description.
-m=LEN request only LEN bytes of response data. Default is 0 which is
interpreted as all that is available. LEN is decimal unless it
has a leading '0x' or trailing 'h'. Equivalent to --maxlen=LEN
in the main description.
-M=VP Equivalent to --vendor=VP in the main description.
-n Equivalent to --name in the main description.
-N, --new
Switch to the newer style options.
-p=PG log page code to access. PG is either an acronym, a page number,
or a page, subpage pair. Available acronyms can be listed with
the --enumerate option. Page (0 to 3f) and subpage (0 to ff)
numbers are comma separated. The numbers are assumed to be hexa-
decimal.
-paramp=PP
PP is the parameter pointer value (in hex) to place in command.
Should be a number between 0 and ffff inclusive.
-pcb show Parameter Control Byte settings (only relevant when log
parameters being output in ASCII).
-ppc sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e.
cleared).
-r use SCSI LOG SELECT command (PCR bit set) to reset the all log
pages (or the given page). Equivalent to --reset in the main
description.
-R Equivalent to --readonly in the main description.
-select
use a LOG SELECT command. Equivalent to --select in the main
description.
-sp sets the Saving Parameters (SP) bit. Default is 0 (i.e.
cleared). Equivalent to --sp in the main description.
-t outputs the temperature. Equivalent to --temperature in the main
description.
-T outputs the transport ('Protocol specific port') log page.
Equivalent to --transport in the main description.
-v increase level of verbosity.
-V print out version string then exit.
-x suppress the INQUIRY command. Equivalent to --no_inq in the main
description.
-? output usage message then exit.
ENVIRONMENT VARIABLES
Since sg3_utils version 1.23 the environment variable
SG3_UTILS_OLD_OPTS can be given. When it is present this utility will
expect the older command line options. So the presence of this environ-
ment variable is equivalent to using --old (or -O) as the first command
line option.
AUTHOR
Written by Douglas Gilbert
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright (C) 2002-2020 Douglas Gilbert
This software is distributed under the GPL version 2. There is NO war-
ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR-
POSE.
SEE ALSO
smartctl(smartmontools), sg_senddiag(8)
sg3_utils-1.45 January 2020 SG_LOGS(8)