572 lines
26 KiB
Groff
572 lines
26 KiB
Groff
.TH SG_LOGS "8" "November 2022" "sg3_utils\-1.48" SG3_UTILS
|
|
.SH NAME
|
|
sg_logs \- access log pages with SCSI LOG SENSE command
|
|
.SH SYNOPSIS
|
|
.B sg_logs
|
|
[\fI\-\-ALL\fR] [\fI\-\-all\fR] [\fI\-\-brief\fR] [\fI\-\-exclude\fR]
|
|
[\fI\-\-filter=FL\fR] [\fI\-\-full\fR] [\fI\-\-hex\fR] [\fI\-\-json[=JO]\fR]
|
|
[\fI\-\-list\fR] [\fI\-\-maxlen=LEN\fR] [\fI\-\-name\fR] [\fI\-\-no_inq\fR]
|
|
[\fI\-\-page=PG\fR] [\fI\-\-paramp=PP\fR] [\fI\-\-pcb\fR] [\fI\-\-ppc\fR]
|
|
[\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-sp\fR]
|
|
[\fI\-\-temperature\fR] [\fI\-\-transport\fR] [\fI\-\-undefined\fR]
|
|
[\fI\-\-vendor=VP\fR] [\fI\-\-verbose\fR] \fIDEVICE\fR
|
|
.PP
|
|
.B sg_logs
|
|
\fI\-\-in=FN\fR [\fI\-\-brief\fR] [\fI\-\-exclude\fR] [\fI\-\-filter=FL\fR]
|
|
[\fI\-\-full\fR] [\fI\-\-hex\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-name\fR]
|
|
[\fI\-\-page=PG\fR] [\fI\-\-pdt=DT\fR] [\fI\-\-raw\fR] [\fI\-\-undefined\fR]
|
|
[\fI\-\-vendor=VP\fR]
|
|
.PP
|
|
.B sg_logs
|
|
\fI\-\-select\fR [\fI\-\-control=PC\fR] [\fI\-\-page=PG\fR] [\fI\-\-raw\fR]
|
|
[\fI\-\-reset\fR] [\fI\-\-sp\fR] [\fI\-\-verbose\fR] \fIDEVICE\fR
|
|
.PP
|
|
.B sg_logs
|
|
\fI\-\-enumerate\fR [\fI\-\-filter=FL\fR] [\fI\-\-help\fR]
|
|
[\fI\-\-vendor=VP\fR] [\fI\-\-version\fR]
|
|
.PP
|
|
.B sg_logs
|
|
[\fI\-a\fR] [\fI\-A\fR] [\fI\-b\fR] [\fI\-c=PC\fR] [\fI\-D=DT\fR] [\fI\-e\fR]
|
|
[\fI\-E\fR] [\fI\-f=FL\fR] [\fI\-F\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-i=FN\fR]
|
|
[\fI\-l\fR] [\fI\-L\fR] [\fI\-m=LEN\fR] [\fI\-M=VP\fR] [\fI\-n\fR]
|
|
[\fI\-p=PG\fR] [\fI\-paramp=PP\fR] [\fI\-pcb\fR] [\fI\-ppc\fR] [\fI\-r\fR]
|
|
[\fI\-R\fR] [\fI\-select\fR] [\fI\-sp\fR] [\fI\-t\fR] [\fI\-T\fR] [\fI\-u\fR]
|
|
[\fI\-v\fR] [\fI\-V\fR] [\fI\-?\fR] [\fI\-x\fR] \fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
This utility sends a SCSI LOG SENSE command to the \fIDEVICE\fR and then
|
|
outputs the response. The LOG SENSE command is used to fetch log pages which,
|
|
if known, are decoded by default. When the \fI\-\-reset\fR and/or
|
|
\fI\-\-select\fR option is given then a SCSI LOG SELECT command is issued
|
|
to the \fIDEVICE\fR. Alternatively one or more log page responses can be in
|
|
a file read using the \fI\-\-in=FN\fR option; in this case those responses
|
|
are decoded and the \fIDEVICE\fR argument, if given, is ignored.
|
|
.PP
|
|
In SPC\-4 revision 5 the 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.
|
|
.PP
|
|
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
|
|
\fIDEVICE\fR and decode its response. The second form fetches data from a
|
|
file (named \fIFN\fR) 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.
|
|
.PP
|
|
When no options are given, just a \fIDEVICE\fR, that is equivalent to calling
|
|
this utility with the \fI\-\-list\fR option. In that case the names of the
|
|
supported log pages (but not subpages) are listed out.
|
|
.SH 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.
|
|
.TP
|
|
\fB\-A\fR, \fB\-\-ALL\fR
|
|
fetch and decode all the log pages and subpages supported by the \fIDEVICE\fR.
|
|
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.
|
|
.br
|
|
Since some vendors don't list all log pages in the "supported log pages and
|
|
subpages" log page, the '\-lll' option can be given in addition. This will
|
|
merge both "supported ..." log pages then, from that resultant merged list,
|
|
fetch page contents.
|
|
.br
|
|
The long option may also appear as \fB\-\-All\fR.
|
|
.br
|
|
This option overrides the \fI\-\-page=PG\fR if the latter is also given.
|
|
.TP
|
|
\fB\-a\fR, \fB\-\-all\fR
|
|
outputs all the log pages supported by the \fIDEVICE\fR. 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.
|
|
.br
|
|
This option overrides the \fI\-\-page=PG\fR if the latter is also given.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-brief\fR
|
|
shorten the amount of output for some log pages. For example the Tape
|
|
Alert log page only outputs parameters whose flags are set when
|
|
\fI\-\-brief\fR is given.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-control\fR=\fIPC\fR
|
|
accepts 0, 1, 2 or 3 for the \fIPC\fR argument:
|
|
.br
|
|
\fB0\fR : current threshold values
|
|
.br
|
|
\fB1\fR : current cumulative values
|
|
.br
|
|
\fB2\fR : default threshold values
|
|
.br
|
|
\fB3\fR : default cumulative values
|
|
.br
|
|
The default value is 1 (i.e. current cumulative values).
|
|
.TP
|
|
\fB\-e\fR, \fB\-\-enumerate\fR
|
|
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 \fIDEVICE\fR argument is ignored. When given once (e.g. '\-e')
|
|
all known pages are listed, sorted in ascending alphabetical acronym order.
|
|
.br
|
|
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.
|
|
.br
|
|
The \fI\-\-filter=FL\fR and \fI\-\-verbose\fR options reduce the output
|
|
of the enumeration.
|
|
.TP
|
|
\fB\-E\fR, \fB\-\-exclude\fR
|
|
this option excludes vendor specific pages and parameters from the output.
|
|
Trying to decode vendor specific pages and parameters does not necessarily
|
|
work well for many reasons. This option limits the output to pages and
|
|
parameters defined by T10.
|
|
.br
|
|
Only parameter fields identified in the drafts as 'vendor specific' are
|
|
excluded. So parameters codes identified as 'reserved' are shown.
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-filter\fR=\fIFL\fR
|
|
\fIFL\fR is either a parameter code when \fIDEVICE\fR is given, or a
|
|
peripheral device type (pdt) (or other) if \fI\-\-enumerate\fR is given.
|
|
.br
|
|
In the parameter code case \fIFL\fR is a value between 0 and 65535 (0xffff)
|
|
and only the parameter section matching that code is output. If the
|
|
\fB\-\-hex\fR option is given the log parameter is output in hexadecimal
|
|
rather than decoding it. If the \fB\-\-hex\fR option is used twice then the
|
|
leading address on each line of hex is removed. If the \fB\-\-raw\fR 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).
|
|
.br
|
|
In the \fI\-\-enumerate\fR case, when \fIFL\fR >= 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 \fIFL\fR is \-1 then the filter does
|
|
nothing which is the same as not giving this option; when \fIFL\fR is \-2
|
|
then only generic pages listed in SPC are enumerated. If \fIFL\fR is \-10
|
|
then only generic direct access like (e.g. disk) pages are enumerated. If
|
|
\fIFL\fR is \-11 then only generic tape like pages (e.g. includes ADC)
|
|
are enumerated.
|
|
.TP
|
|
\fB\-F\fR, \fB\-\-full\fR
|
|
this option only applies to the Application client log page. Typically that
|
|
log page has more than 16,000 bytes of user supplied data. Rather than
|
|
print it all out, the default is to print out the first 64 bytes of data.
|
|
When this option is given, the application client log pages is fully
|
|
decoded.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
print out the usage message then exit.
|
|
.TP
|
|
\fB\-H\fR, \fB\-\-hex\fR
|
|
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 \fI\-\-in=FN\fR
|
|
option.
|
|
.br
|
|
A weaker form of this option, called \fI\-\-undefined\fR, handles the
|
|
formatting of hexadecimal output for fields that this utility is unable to
|
|
decode.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-in\fR=\fIFN\fR
|
|
This option may be used in two different contexts. One is with the
|
|
\fI\-\-select\fR to send a LOG SELECT command to the given \fIDEVICE\fR;
|
|
see the LOG SELECT section below.
|
|
.br
|
|
The other context is with no \fIDEVICE\fR argument given in which case
|
|
the contents of \fIFN\fR 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 \fIFN\fR while the peripheral device type is either
|
|
generic (i.e. from SPC) or the value given by \fI\-\-pdt=DT\fR.
|
|
.br
|
|
\fIFN\fR 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 \fI\-\-raw\fR option is also given then \fIFN\fR is
|
|
treated as binary.
|
|
.br
|
|
For compatibility with other utilities in this package "inhex" may also be
|
|
used as this (long) option name.
|
|
.TP
|
|
\fB\-j\fR, \fB\-\-json[\fR=\fIJO\fR]
|
|
output is in JSON format instead of human readable form. See sg3_utils_json
|
|
manpage or use '?' for \fIJO\fR in order to have a summary printed to stderr.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-list\fR
|
|
lists the names of the logs sense pages supported by this device. This is
|
|
done by reading the "supported log pages" log page. When used once only
|
|
log pages, but not subpages, are listed. When used twice the "supported
|
|
log pages and subpages" log page is output. Some vendors do not list some
|
|
log pages (e.g. those without any subpages) in the "supported log pages
|
|
and subpages" log page. To get a full inventory, this option can be used
|
|
three times (e.g. '\-lll') and the output of the two log pages is merged.
|
|
Even if the "supported log pages and subpages" log page is not supported
|
|
using this option three times will yield a list from the "supported log
|
|
pages" log page. In the absence of other options, the page/subpage names,
|
|
but not their contents, are shown when this option is given.
|
|
.br
|
|
The '\-lll' form may be useful with the \fI\-\-ALL\fR option to show the
|
|
contents of all pages referred to in either the "supported log page" or
|
|
the "supported log page and subpage" log pages.
|
|
.TP
|
|
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
|
|
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 \fILEN\fR
|
|
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 \fILEN\fR are not accepted. 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.
|
|
.br
|
|
The default \fILEN\fR is 65532 unless the \fI\-\-in=FN\fR option is given;
|
|
in that case the default is 262144 .
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-name\fR
|
|
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.
|
|
.br
|
|
This option is superseded by the \fI\-\-json[=JO]\fR option. If both are
|
|
given then this option is ignored.
|
|
.TP
|
|
\fB\-x\fR, \fB\-\-no_inq\fR
|
|
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.
|
|
.br
|
|
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).
|
|
.TP
|
|
\fB\-O\fR, \fB\-\-old\fR
|
|
Switch to older style options. Please use as first option.
|
|
.TP
|
|
\fB\-p\fR, \fB\-\-page\fR=\fIPG\fR
|
|
log page name/number to access. \fIPG\fR is either an acronym, a page number,
|
|
or a page, subpage number pair. Available acronyms can be listed with the
|
|
\fI\-\-enumerate\fR 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".
|
|
.br
|
|
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).
|
|
.TP
|
|
\fB\-P\fR, \fB\-\-paramp\fR=\fIPP\fR
|
|
\fIPP\fR is the parameter pointer value to place in a field of that name in
|
|
the LOG SENSE cdb. A number in the range 0 to 65535 (0x0 to 0xffff) is
|
|
expected. When a value greater than 0 is given the \fI\-\-ppc\fR option
|
|
should be selected. The default value is 0.
|
|
.br
|
|
For log pages that have parameter codes, the \fIDEVICE\fR should return
|
|
only parameters code equal to \fIPP\fR or higher in its response.
|
|
.TP
|
|
\fB\-q\fR, \fB\-\-pcb\fR
|
|
show Parameter Control Byte settings (only relevant when log parameters
|
|
being output in ASCII). This byte includes the DU and TSD bits plus
|
|
the 'Format and linking' field (2 bits wide).
|
|
.TP
|
|
\fB\-D\fR, \fB\-\-pdt\fR=\fIDT\fR
|
|
\fIDT\fR is the peripheral device type (PDT) that is used when it is not
|
|
available from the \fIDEVICE\fR. There are two main cases of this: with
|
|
the \fI\-\-pdt=DT\fR without a \fIDEVICE\fR (e.g. when \fI\-\-in=FN\fR
|
|
is used) and when \fI\-\-no_inq\fR is used with a \fIDEVICE\fR.
|
|
.br
|
|
\fIDT\fR may be -1 which is the default value. This value may select any
|
|
device type but favours the lower numbers (e.g. the PDT of disks is 0).
|
|
.TP
|
|
\fB\-Q\fR, \fB\-\-ppc\fR
|
|
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.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-raw\fR
|
|
output the response in binary to stdout. Error messages and warnings are
|
|
output to stderr.
|
|
.br
|
|
This option may also be given together with \fI\-\-in=FN\fR in which case
|
|
the contents of \fIFN\fR are interpreted as binary data (and the response is
|
|
decoded as normal, not dumped as binary).
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-readonly\fR
|
|
open the \fIDEVICE\fR read\-only (e.g. in Unix with the O_RDONLY flag). The
|
|
default action is to try and open \fIDEVICE\fR 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 \fIDEVICE\fR and if it fails, this utility will exit. Note that
|
|
options like \fI\-\-select\fR most likely need a read\-write open.
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-reset\fR
|
|
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. \fI\-\-sp\fR option which defaults to 0) and the
|
|
\fIPC\fR ("page control") value (which defaults to 1). Supplying this option
|
|
implies the \fI\-\-select\fR 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).
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-select\fR
|
|
use a LOG SELECT command. The default action (i.e. when neither this option
|
|
nor \fI\-\-reset\fR is given) is to do a LOG SENSE command. See the LOG
|
|
SELECT section.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-sp\fR
|
|
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 which causes the \fIDEVICE\fR to periodically save all
|
|
saveable log parameters to non\-volatile storage.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-temperature\fR
|
|
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).
|
|
.TP
|
|
\fB\-T\fR, \fB\-\-transport\fR
|
|
outputs the transport ('Protocol specific port') log page. Equivalent to
|
|
setting '\-\-page=18h'.
|
|
.TP
|
|
\fB\-u\fR, \fB\-\-undefined\fR
|
|
to see fields decoded, the \fI\-\-hex\fR option cannot be used. However some
|
|
fields are not defined in the T10 documents and in that case they are output
|
|
in hex. This option controls the format of 'undefined' fields when they
|
|
output in hex. Multiple uses of this option has the same sense as the
|
|
\fI\-\-hex\fR option. For example '\-uu' will output undefined fields in
|
|
hexadecimal with an ASCII rendering to the right of each line.
|
|
.TP
|
|
\fB\-M\fR, \fB\-\-vendor\fR=\fIVP\fR
|
|
where \fIVP\fR 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 \fIVP\fR of "xxx" will list the
|
|
available acronyms.
|
|
.br
|
|
If this option is used with \fI\-\-page=PG\fR and \fIPG\fR is an acronym
|
|
then this option is ignored. If \fIPG\fR is a number (e.g. 0xc0) then
|
|
\fIVP\fR is used to choose the which vendor specific page (e.g. sharing
|
|
page number 0xc0) to decode.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
increase level of verbosity. When used with \fI\-\-enumerate\fR, in the
|
|
list of known log page names, those that have no associated decode logic
|
|
are followed by "[hex only]".
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
print out version string then exit.
|
|
.SH 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.
|
|
.PP
|
|
The \fI\-\-select\fR (or \fI\-\-reset\fR) option is required to issue a LOG
|
|
SELECT command. If the \fI\-\-in=FN\fR option is not given (or \fIFN\fR is
|
|
effectively empty) then the Parameter list length field is set to zero. If
|
|
the \fI\-\-in=FN\fR 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.
|
|
.PP
|
|
Other options that are active with the LOG SELECT command are
|
|
\fI\-\-control=PC\fR, \fI\-\-reset\fR (which sets the PCR bit) and
|
|
\fI\-\-sp\fR.
|
|
.SH
|
|
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.
|
|
.PP
|
|
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 \fI\-\-in=FN\fR 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>'.
|
|
.SH 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 \fI\-\-maxlen=LEN\fR option will do a single fetch.
|
|
A value of 252 should be a safe starting point.
|
|
.PP
|
|
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.
|
|
.PP
|
|
The simplest way to find which log pages can be decoded by this utility is
|
|
to use the \fI\-\-enumerate\fR option. Some page names are known but there
|
|
is no decode logic; such cases have "[hex only]" after the log page name
|
|
when the \fI\-\-verbose\fR option is given with \fI\-\-enumerate\fR.
|
|
.PP
|
|
Vendors are specifically permitted by the SPC\-6 to _not_ report all pages
|
|
and subpages supported by a device. That weakens the usefulness of the pages
|
|
that report a list of supported pages and subpages. One guarantee which is
|
|
given is that the pages reported shall be in ascending order.
|
|
.SH EXIT STATUS
|
|
The exit status of sg_logs is 0 when it is successful. Otherwise see
|
|
the sg3_utils(8) man page.
|
|
.SH 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 \fI\-\-old\fR (or \fI\-O\fR) as the
|
|
first option. See the ENVIRONMENT VARIABLES section for another way to
|
|
force the use of these older command line options.
|
|
.PP
|
|
Options with arguments or with two or more letters can have an extra '\-'
|
|
prepended. For example: both '\-pcb' and '\-\-pcb' are acceptable.
|
|
.TP
|
|
\fB\-a\fR
|
|
outputs all the log pages supported by the \fIDEVICE\fR.
|
|
Equivalent to \fI\-\-all\fR in the main description.
|
|
.TP
|
|
\fB\-A\fR
|
|
outputs all the log pages and subpages supported by the \fIDEVICE\fR.
|
|
Equivalent to \fI\-\-ALL\fR in the main description.
|
|
.TP
|
|
\fB\-c\fR=\fIPC\fR
|
|
Equivalent to \fI\-\-control=PC\fR in the main description.
|
|
.TP
|
|
\fB\-D\fR=\fIDT\fR
|
|
Equivalent to \fI\-\-pdt=DT\fR in the main description.
|
|
.TP
|
|
\fB\-e\fR
|
|
enumerate internal tables to show information about known log pages.
|
|
Equivalent to \fI\-\-enumerate\fR in the main description.
|
|
.TP
|
|
\fB\-E\fR
|
|
Equivalent to \fI\-\-exclude\fR in the main description.
|
|
.TP
|
|
\fB\-h\fR
|
|
suppresses decoding of known log sense pages and prints out the
|
|
response in hex instead.
|
|
.TP
|
|
\fB\-i\fR=\fIFN\fR
|
|
\fIFN\fR 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.
|
|
.TP
|
|
\fB\-H\fR
|
|
same action as '\-h' in this section and equivalent to \fI\-\-hex\fR in
|
|
the main description.
|
|
.TP
|
|
\fB\-l\fR
|
|
lists the names of all logs sense pages supported by this \fIDEVICE\fR.
|
|
Equivalent to \fI\-\-list\fR in the main description.
|
|
.TP
|
|
\fB\-L\fR
|
|
lists the names of all logs sense pages and subpages supported by this
|
|
\fIDEVICE\fR. Equivalent to '\-\-list \-\-list' in the main description.
|
|
.TP
|
|
\fB\-m\fR=\fILEN\fR
|
|
request only \fILEN\fR bytes of response data. Default is 0 which is
|
|
interpreted as all that is available. \fILEN\fR is decimal unless it has
|
|
a leading '0x' or trailing 'h'. Equivalent to \fI\-\-maxlen=LEN\fR in
|
|
the main description.
|
|
.TP
|
|
\fB\-M\fR=\fIVP\fR
|
|
Equivalent to \fI\-\-vendor=VP\fR in the main description.
|
|
.TP
|
|
\fB\-n\fR
|
|
Equivalent to \fI\-\-name\fR in the main description.
|
|
.TP
|
|
\fB\-N\fR, \fB\-\-new\fR
|
|
Switch to the newer style options.
|
|
.TP
|
|
\fB\-p\fR=\fIPG\fR
|
|
log page code to access. \fIPG\fR is either an acronym, a page number, or
|
|
a page, subpage pair. Available acronyms can be listed with the
|
|
\fI\-\-enumerate\fR option. Page (0 to 3f) and subpage (0 to ff) numbers
|
|
are comma separated. The numbers are assumed to be hexadecimal.
|
|
.TP
|
|
\fB\-paramp\fR=\fIPP\fR
|
|
\fIPP\fR is the parameter pointer value (in hex) to place in command.
|
|
Should be a number between 0 and ffff inclusive.
|
|
.TP
|
|
\fB\-pcb\fR
|
|
show Parameter Control Byte settings (only relevant when log parameters
|
|
being output in ASCII).
|
|
.TP
|
|
\fB\-ppc\fR
|
|
sets the Parameter Pointer Control (PPC) bit. Default is 0 (i.e. cleared).
|
|
.TP
|
|
\fB\-r\fR
|
|
use SCSI LOG SELECT command (PCR bit set) to reset the all log pages (or
|
|
the given page). Equivalent to \fI\-\-reset\fR in the main description.
|
|
.TP
|
|
\fB\-R\fR
|
|
Equivalent to \fI\-\-readonly\fR in the main description.
|
|
.TP
|
|
\fB\-select\fR
|
|
use a LOG SELECT command. Equivalent to \fI\-\-select\fR in the main
|
|
description.
|
|
.TP
|
|
\fB\-sp\fR
|
|
sets the Saving Parameters (SP) bit. Default is 0 (i.e. cleared).
|
|
Equivalent to \fI\-\-sp\fR in the main description.
|
|
.TP
|
|
\fB\-t\fR
|
|
outputs the temperature. Equivalent to \fI\-\-temperature\fR in the main
|
|
description.
|
|
.TP
|
|
\fB\-T\fR
|
|
outputs the transport ('Protocol specific port') log page. Equivalent
|
|
to \fI\-\-transport\fR in the main description.
|
|
.TP
|
|
\fB\-v\fR
|
|
increase level of verbosity.
|
|
.TP
|
|
\fB\-V\fR
|
|
print out version string then exit.
|
|
.TP
|
|
\fB\-x\fR
|
|
suppress the INQUIRY command. Equivalent to \fI\-\-no_inq\fR in the main
|
|
description.
|
|
.TP
|
|
\fB\-?\fR
|
|
output usage message then exit.
|
|
.SH 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 environment variable is equivalent to
|
|
using \fI\-\-old\fR (or \fI\-O\fR) as the first command line option.
|
|
.SH AUTHOR
|
|
Written by Douglas Gilbert
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2002\-2022 Douglas Gilbert
|
|
.br
|
|
This software is distributed under the GPL version 2. There is NO
|
|
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
|
|
.SH "SEE ALSO"
|
|
.B smartctl(smartmontools), sg_senddiag(8)
|