| .TH SG_LOGS "8" "February 2016" "sg3_utils\-1.42" 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\-\-control=PC\fR] |
| [\fI\-\-enumerate\fR] [\fI\-\-enum_vendor\fR] [\fI\-\-filter=FL\fR] |
| [\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-in=FN\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\-\-raw\fR] |
| [\fI\-\-readonly\fR] [\fI\-\-reset\fR] [\fI\-\-select\fR] [\fI\-\-sp\fR] |
| [\fI\-\-temperature\fR] [\fI\-\-transport\fR] [\fI\-\-verbose\fR] |
| [\fI\-\-version\fR] \fIDEVICE\fR |
| .PP |
| .B sg_logs |
| [\fI\-a\fR] [\fI\-A\fR] [\fI\-b\fR] [\fI\-c=PC\fR] [\fI\-e\fR] [\fI\-E\fR] |
| [\fI\-f=FL\fR] [\fI\-h\fR] [\fI\-H\fR] [\fI\-i=FN\fR] [\fI\-l\fR] [\fI\-L\fR] |
| [\fI\-m=LEN\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\-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. Known |
| log pages can be decoded. When the \fI\-\-reset\fR and/or \fI\-\-select\fR |
| option is given then a SCSI LOG SELECT command is issued. |
| .PP |
| 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. |
| .PP |
| 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. |
| .SH OPTIONS |
| Arguments to long options are mandatory for short options as well. |
| .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 the 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. |
| .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 the response, the corresponding log page is fetched and |
| displayed. When used twice (e.g. '\-aa') all log pages and subpages are |
| fetched. |
| .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 internal tables about |
| known log pages including their names and acronyms. If given \fIDEVICE\fR |
| is ignored. When given once (e.g. '\-e') all known pages are listed, sorted |
| in ascending 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. |
| .br |
| The \fI\-\-filter=FL\fR and \fI\-\-verbose\fR options modify the output |
| of the enumeration. |
| .TP |
| \fB\-E\fR, \fB\-\-enum_vendor\fR |
| this option is used to output information held in internal tables about |
| known vendor specific log pages including their names and acronyms. |
| .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. |
| The \fB\-\-hex\fR option outputs log parameter 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 are those pages that list supported log pages. |
| .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\-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 mode 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. |
| .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 device type is either generic (i.e. from |
| SPC) or the value given by \fI\-\-filter=FL\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. |
| .TP |
| \fB\-l\fR, \fB\-\-list\fR |
| 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. |
| .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. \fILEN\fR 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. |
| .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. |
| .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. |
| .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 decimal number in the range 0 to 65535 (0xffff) is |
| expected. When a value greater than 0 is given the \fI\-\-ppc\fR option |
| should be selected. The default value is 0. |
| .TP |
| \fB\-q\fR, \fB\-\-pcb\fR |
| show Parameter Control Byte settings (only relevant when log parameters |
| being output in ASCII). |
| .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. |
| .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 (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" until something is done. |
| .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 as this instructs the device to periodically save all |
| saveable log parameters to non\-volatile locations. |
| .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\-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 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 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 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. |
| .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. |
| .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 . 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. |
| .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 device. |
| Equivalent to \fI\-\-all\fR in the main description. |
| .TP |
| \fB\-A\fR |
| outputs all the log pages and subpages supported by the device. |
| Equivalent to '\-\-all \-\-all' in the main description. |
| .TP |
| \fB\-c\fR=\fIPC\fR |
| Equivalent to \fI\-\-control=PC\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 |
| enumerate internal tables to show information about known vendor specific |
| log pages. Equivalent to \fI\-\-enum_vendor\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 device. |
| 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 |
| device. 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\-n\fR |
| Equivalent to \fI\-\-name\fR in the main description. |
| .TP |
| \fB\-N\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 AUTHOR |
| Written by Douglas Gilbert |
| .SH "REPORTING BUGS" |
| Report bugs to <dgilbert at interlog dot com>. |
| .SH COPYRIGHT |
| Copyright \(co 2002\-2016 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) |