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
This utility sends a SCSI LOG SENSE command to the
DEVICE and then
outputs 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 introduced 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 interface which is maintained for
backward compatibility.
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 peripheral 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 parameters. 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
subpage 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 hexadecimal 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 indicated 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 output 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
subpage (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 command). 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).
Supplying 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 current log page
parameters (as indicated by the DS and TSD parameter codes) in some
non-volatile location. Hence the log parameters will be preserved across
power cycles. This option is typically 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.
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
command. 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 buffer and its length in bytes is placed in the Parameter list length
field.
Other options that are active with the LOG SELECT command are
--control=PC,
--reset (which sets the PCR bit) and
--sp.
This is the name of a log page that acts as a container for data provided 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>'.
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.
The exit status of sg_logs is 0 when it is successful. Otherwise see the
sg3_utils(8) man page.
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
section.
- -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
hexadecimal.
-
-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.
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 environment variable is equivalent to using
--old (or
-O) as the first command line option.
Written by Douglas Gilbert
Report bugs to <dgilbert at interlog dot com>.
Copyright © 2002-2020 Douglas Gilbert
This software is distributed under the GPL version 2. There is NO warranty; not
even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
smartctl(smartmontools), sg_senddiag(8)