Provided by: sg3-utils_1.40-0ubuntu1_amd64 
NAME
sg_logs - access log pages with SCSI LOG SENSE command
SYNOPSIS
sg_logs [--all] [--brief] [--control=PC] [--filter=PARC] [--help] [--hex] [--in=FN]
[--list] [--maxlen=LEN] [--name] [--no_inq] [--page=PG[,SPG]] [--paramp=PP] [--pcb]
[--ppc] [--raw] [--readonly] [--reset] [--select] [--sp] [--temperature] [--transport]
[--verbose] [--version] DEVICE
sg_logs [-a] [-A] [-b] [-c=PC] [-f=PARC] [-h] [-H] [-i=FN] [-l] [-L] [-m=LEN] [-n]
[-p=PG[,SPG]] [-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 outputs the response.
The LOG SENSE command is used to fetch log pages. Known log pages are decoded by default.
When the --reset and/or --select option is given then a SCSI LOG SELECT command is issued.
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.
This utility supports two command line syntaxes, the preferred one is shown first in the
synopsis and explained in this section. A later section on the old command line syntax
outlines the second group of options.
OPTIONS
Arguments to long options are mandatory for short options as well.
-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 the 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).
-f, --filter=PARC
only output the log parameter whose parameter code (a number between 0 and 65535)
matches PARC. PARC is assumed to be decimal unless a hexadecimal indication is
given (e.g. a leading '0x' or a trailing 'h'). The --hex option outputs log
parameter in hexadecimal rather than decoding it. If the --hex option is used twice
then the leading address on each kine 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 are
those pages that list supported log pages.
-h, --help
print out the usage message then exit.
-H, --hex
The default action is to decode known mode page numbers (and subpage numbers) into
text. When this option is used once, the response is output in hexadecimal.
-i, --in=FN
FN is treated as a file name (or '-' for stdin) which contains ASCII hexadecimal or
binary representing a log page that will be sent as parameter data of a LOG SELECT
command. 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. See the LOG SELECT section.
-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. 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.
-p, --page=PG[,SPG]
log page code to access. PG is expected to be a decimal number between 0 and 63
inclusive. A hexadecimal number can be specified by a leading "0x" or a trailing
"h" so the valid range is 0x to 0x3f. Common log page codes are listed below.
Optionally SPG, a subpage code, can be given. SPG is expected to be a decimal or
hex number between 0 and 255 inclusive.
-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.
-r, --raw
output the response in binary to stdout. Error messages and warnings are output to
stderr.
-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 (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" until something is done.
-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'.
-v, --verbose
increase level of verbosity.
-V, --version
print out version string then exit.
LOG SELECT
The 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 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.
APPLICATION CLIENT
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>'.
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 device 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.
Here is a list of log pages that are decoded by this utility. [The code values can be
given to '--page=' as is, with a trailing "h" instead of the leading "0x", or as their
decimal equivalents.]:
0x0 Supported log pages
0x0,0xff Supported log pages and subpages
0x1 Buffer over-run/under-run
0x2 Write error counter
0x3 Read error counter
0x4 Read reverse error counter
0x5 Verify error counter
0x6 Non-medium error
0x7 Last n error events
0x8 Format status (sbc-2)
0xb Last n deferred errors or asynchronous events
0xc Logical block provisioning (sbc-3) or
Sequential access device (ssc-2)
0xd Temperature
0xe Start-stop cycle counter
0xf Application client
0x10 Self-test results
0x11 Solid state media
0x15 Background scan results (sbc-3)
0x16 ATA pass-through results (sat-3)
0x17 Non-volatile cache (sbc-3)
0x18 Protocol specific port (SAS transport)
0x19 General statistics and performance
0x1a Power condition transitions
0x2f Informational exceptions
0x37 Seagate cache (vendor, disk)
0x3e Seagate factory (vendor, disk)
In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the
2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For
example "sg_logs -a /dev/sda" will work in the 2.6 series kernels.
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 .
In sg3_utils version 1.23 and later these older options can be selected by either setting
the SG3_UTILS_OLD_OPTS environment variable or using '--old' (or '-O) as the first option.
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.
-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.
-n Equivalent to --name in the main description.
-N switch to the newer style options.
-p=PG[,SPG]
PG is the log page code to access. Should be a hexadecimal number between 0 and 3f
inclusive. If given SPG is the log subpage code. SPG should be a hexadecimal
number between 0 and ff inclusive. The subpage code of 'ff' can be thought of as a
wildcard.
-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.
AUTHOR
Written by Douglas Gilbert
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2002-2014 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.
SEE ALSO
smartctl(smartmontools), sg_senddiag(8)