SG_LOGS(8)

💫 sg_logs — the SCSI log page queen (section 8, from sg3_utils) 💫

okay so bestie, welcome to sg_logs, straight out of SG3_UTILS manual section 8 — she's the one who talks to your device's log pages and actually makes sense of them ✨

🎀 SYNOPSIS 🎀

here's the vibe check on how you call her — five whole forms, no cap:

sg_logs [--ALL] [--all] [--brief] [--exclude] [--filter=FL] [--full]
[--hex] [--json[=JO]] [--js-file=JFN] [--list] [--maxlen=LEN] [--name]
[--no_inq] [--page=PG] [--paramp=PP] [--pcb] [--ppc] [--pdt=DT] [--raw]
[--readonly] [--sp] [--temperature] [--transport] [--undefined]
[--vendor=VP] [--verbose] DEVICE

form two, the file girlie:

sg_logs --inhex=FN  [--ALL] [--all] [--brief] [--exclude] [--filter=FL]
[--full] [--hex] [--json[=JO]] [--js-file=JFN] [--list] [--name]
[--page=PG] [--pdt=DT] [--raw] [--undefined] [--vendor=VP]

form three, the one that sends stuff:

sg_logs --select  [--control=PC] [--page=PG] [--raw] [--reset] [--sp]
[--verbose] DEVICE

form four, the management bestie:

sg_logs --enumerate  [--filter=FL] [--help] [--vendor=VP] [--version]

and form five, the legacy edition (we love her but she's deprecated):

sg_logs [-a] [-A] [-b] [-c=PC] [-D=DT] [-e] [-E] [-f=FL] [-F] [-h] [-H]
[-i=FN] [-l] [-L] [-m=LEN] [-M=VP] [-n] [-p=PG] [-paramp=PP] [-pcb]
[-ppc] [-r] [-R] [-select] [-sp] [-t] [-T] [-u] [-v] [-V] [-?] [-x]
DEVICE

🦋 DESCRIPTION 🦋

so like, what does she do? This utility sends a SCSI LOG SENSE command to the DEVICE and then outputs the response. The LOG SENSE command is the whole point — it fetches log pages, and if they're known pages, they get decoded by default (iconic behaviour honestly).

When you give the --reset and/or --select option, that's a whole different mood: a SCSI LOG SELECT command gets issued to the DEVICE instead. Alternatively, one or more log page responses can be chilling in a file, read using the --inhex=FN option — in that case those responses get decoded and the DEVICE argument, if you even gave one, is ignored. rude but fair 💅

real talk: 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. (yes, that double "to the" is in the original, she's quirky, we keep her fr fr.) 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 up there is divided into five forms, so let's break it down diva-style:

1. the first form shows the options you can use to send a LOG SENSE command to the DEVICE and decode its response
2. the second form fetches data from a file (named FN) and decodes it as if it were a response from a LOG SENSE command
3. the third form shows the options you can use to send a LOG SELECT command
4. the fourth form groups various management options
5. the last form shows the older, deprecated command line interface which is maintained for backward compatibility

⚠️ okay important: when no options are given, just a DEVICE, that is equivalent to calling this utility with the --list option. In that case the names of the supported log pages (but not subpages) are listed out. iykyk 🌸

---

✨ OPTIONS ✨

Arguments to long options are mandatory for short options as well (yes, both, no skipping). The options are arranged in alphabetical order based on the long option name — she's organized like that 🫶

• -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. In this case this utility continues by fetching the supported log pages log page instead. In other words if the --ALL option fails then the --all is used instead — the reason being that almost certainly the DEVICE does not have any log subpages to report. To force an error if the fetch of the supported log pages and subpages log page fails use both the --ALL and --full options. 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. This option overrides the --page=PG if the latter is also given. 💀
• -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. This option overrides the --page=PG if the latter is also given.
• -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. lowkey the best option when you're scrolling in a terminal that's 40 lines tall 😭
• -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. 🧚
• -E, --exclude — 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. Only parameter fields identified in the drafts as 'vendor specific' are excluded. So parameters codes identified as 'reserved' are shown. periodt.
• -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. 🔥
• -F, --full — this option is only used in two situations: with the Application client (AC) log page and with the --ALL option. Typically the AC 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. When both this option and the --ALL option are given, then this utility will exit with an error if the Supported log pages and subpages log page is not available.
• -h, --help — print out the usage message then exit. our fave, zero commitment 🎀
• -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 --inhex=FN option. A weaker form of this option, called --undefined, handles the formatting of hexadecimal output for fields that this utility is unable to decode.
• -i, --in=FN — Same as --inhex=FN option. Kept for backward compatibility. she's vintage 💖
• -i, --inhex=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. one or more 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. 🌈
• -j[=JO], --json[=JO] — output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=". See sg3_utils_json manpage or use '?' for JO to get a summary. ngl the JSON girlies are eating 🍓
• -J, --js-file=JFN — output is in JSON format and it is sent to a file named JFN. If that file exists then it is truncated. By default, the JSON output is sent to stdout. When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values. ✨

---

(part 1 done — more scroll energy coming, don't go anywhere bestie) 🦋

• -l, --list — bestie, this one just lists the names of the log sense pages your device is serving up. How? By reading the "supported log pages" log page, obvi. Use it once and you get log pages only, no subpages. Use it twice and you get the "supported log pages and subpages" log page output. ⚠️ Some vendors are messy and don't list some log pages (like the ones with no subpages at all) in that "supported log pages and subpages" page. So to get a full inventory, hit it three times (like -lll) and the output of the two log pages gets merged. And even if "supported log pages and subpages" isn't supported at all, three times still gets you a list from the "supported log pages" log page. If you don't pass any other options, this shows the page/subpage names but not their contents. The -lll form is lowkey useful with the --ALL 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. 💅
• -m, --maxlen=LEN — sets the "allocation length" field in the LOG SENSE cdb. It's the max length in bytes the response will be. If you skip this option (or set LEN to 0) the utility first fetches the 4 byte response, then does a second access with the length that first (4 byte) response told it. Negative values and 1 for LEN are not accepted — don't even try it. Responses can be huge (like the background scan results log page 👀) and this option limits how much info comes back. Default LEN is 65532 unless the --in=FN option is given; in that case the default is 262144.
• -n, --name — decodes some log pages into name=value entries, one per line. The name has no space in it, may be abbreviated, and the value is decimal unless it's prefixed with 0x. Nesting shows up as leading spaces. This form is meant to be relatively easy to parse (iykyk). 🫶 This option is superseded by the --json[=JO] option — if you give both, this one gets ignored, periodt.
• -x, --no_inq — suppresses the output of info obtained from an initial call to the INQUIRY command for the standard response. The default (assuming some other options that suppress this output aren't also given) is to output several device identification strings. Give it twice (or more) and no INQUIRY command is sent at all, so there's no device identification string output either. Also, the peripheral device type (PDT) field won't be obtained, so the utility won't be able to differentiate between some log pages that are device dependent. It'll just assume a PDT of 0 (i.e. a disk) unless you pass --pdt=DT. 🙈
• -O, --old — switches to older style options. Please use as the first option. 💀
• -p, --page=PG — the 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're decimal unless you give a hexadecimal indication — hex 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 that goes 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 you give a value greater than 0, the --ppc option should be selected. Default value is 0. For log pages that have parameter codes, the DEVICE should return only parameters with code equal to PP or higher in its response.
• -q, --pcb — show Parameter Control Byte settings (only relevant when log parameters are being output in ASCII). This byte includes the DU and TSD bits plus the 'Format and linking' field (2 bits wide). 🎀
• -D, --pdt=DT — DT is the peripheral device type (PDT) used when it isn't available from the DEVICE. There are several cases: when the DEVICE isn't given (e.g. when the --inhex=FN or --enumerate option is given) and when DEVICE is given and is coupled with the --no_inq option. That stops this utility from sending the SCSI INQUIRY command, which is where this utility usually finds the PDT associated with the log pages being decoded. Numerical values between -1 and 31 (inclusive) may be used, where -1 implies what's in SPC. SCSI Primary Commands (SPC) are common to all SCSI devices. Names like 'tape', 'disk' and 'processor' may also be given for DT. The default is 0 or 'disk' for SBC (and the associated standard acronym may also be given, which is 'sbc' in this case). 🦋
• -Q, --ppc — sets the Parameter Pointer Control (PPC) bit in the LOG SENSE cdb. Default is 0 (i.e. cleared). Heads up: this bit was made obsolete in SPC-4 revision 18. 💀
• -r, --raw — output the response in binary to stdout. Error messages and warnings go 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 to open DEVICE read-write first, then if that fails, try to open again read-only. BUT — and this is the gag — 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, bestie.
• -R, --reset — use the SCSI LOG SELECT command (with the PCR bit set) to reset all log pages (or the given page). Exactly what gets reset depends on the accompanying SP bit (i.e. the --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. It may be required to clear log pages if a counter reaches its maximum value, since the log page the counter lives in will stay "stuck" at its max value until some user interaction (e.g. calling sg_logs with this option). 🔥

Ngl, the original page gives both --readonly and --reset the short option -R. That's not a typo on my end, bestie — that's just how it is. Use the long forms if you're not trying to have a chaotic day. 💀

• -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 get 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 DEVICE to periodically save all saveable log parameters to non-volatile storage.
• -t, --temperature — outputs the temperature. 🌡️ First it looks in the temperature log page, and if that's not available it 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'. 🚀
• -u, --undefined — so, to see fields decoded, the --hex option can't be used. However, some fields aren't defined in the T10 documents, and in that case they get output in hex. This option controls the format of 'undefined' fields when they're output in hex. Multiple uses of this option has the same sense as the --hex option. For example '-uu' will output undefined fields in hexadecimal with an ASCII rendering to the right of each line. 💅
• -M, --vendor=VP — where VP is a vendor/manufacturer (e.g. "sea" for Seagate) or a 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 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. That's it, that's the whole vibe. ⭐

---

💖 LOG SELECT 💖

Okay so the SCSI LOG SELECT command — it's the write-y sibling of LOG SENSE. You can use it 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 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. No cap, that's just how it be.

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 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 🦋

Okay bestie, so 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. Slay.

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>. Obsessed with this little container vibe. 💖

🌈 INHEX INSTEAD OF DEVICE 🌈

This section applies when the --inhex=FN option is used and there is no DEVICE argument. This can be viewed as a replay facility where the FN file was created by a prior invocation of this utility, most likely with the '-HHHHH' option, with command line output redirection used to create FN.

If the --all option is given once then all pages (but not subpages) found in FN will be decoded, or output in hex if this utility is unable to decode some of them. If the --all option is given two or more times then all pages and subpages found in FN will be decoded. In both cases pages are decoded in the order they are found in FN.

Next, if the --page=PG] option is given, then FN is searched for a match on PG and, if found, that log (sub)page is decoded. If the --list option is given once, then the Supported log pages log page [0x0,0x0] is decoded, if present. If the --list option is given two or more times, then the Supported Log Pages and Subpages log page [0x0,0xff] is decoded, if present.

If none of the above selection options are given, then this utility will attempt to decode the first log page found in FN. If there are more log pages following the first one in FN then they are ignored. 🙈 Replay era, no cap.

💜 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. Double fetch, but make it fashion.

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.

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. 📈 At least they’re sorting, bestie.

🎀 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 in the main description.
• -c=PC — Equivalent to --control=PC in the main description.
• -D=DT — Equivalent to --pdt=DT in the main description.
• -e — enumerate internal tables to show information about known log pages. Equivalent to --enumerate in the main description.
• -E — Equivalent to --exclude 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.

🌸 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 --old (or -O) as the first command line option. 💅 Environment variable said “go old school,” and honestly? Respect.

💖 AUTHOR 💖

Written by Douglas Gilbert

🐛 REPORTING BUGS 🐛

Report bugs to <dgilbert at interlog dot com>.

📜 COPYRIGHT 📜

Copyright © 2002-2023 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)

---

This page is living that sg3_utils-1.48 life from May 2023 on SG_LOGS(8), and that’s the whole vibe check, bestie 💜✨