SG_SENDDIAG(8)

📦
version 1.49 · 3 versions
, in arch rolling, nixpkgs unstable

🎀 sg_senddiag — the SEND DIAGNOSTIC bestie 🎀

ok so welcome to SG_SENDDIAG(8), part of the SG3_UTILS fam 💖 this is the manual page for the sg_senddiag utility, and bestie, it's lowkey the whole diagnostic vibe.

✨ NAME ✨

  • sg_senddiag — performs a SCSI SEND DIAGNOSTIC command 💅

🌸 SYNOPSIS 🌸

sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list] [--maxlen=LEN]
[--page=PG] [--pf] [--raw=H,H...] [--raw=-] [--selftest=ST] [--test]
[--timeout=SECS] [--uoff] [--verbose] [--version] DEVICE

sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-]
[-s=ST] [-t] [-T=SECS] [-uoff] [-v] [-V] [-?]  DEVICE

🦋 DESCRIPTION 🦋

So, this utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. That's it, that's the whole personality. It can issue self-tests, find supported diagnostic pages, or send arbitrary diagnostic pages — pick your fighter ✨

When the --list option and a DEVICE are given, the utility sends a SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e. the page numbers of supported diagnostic pages). Iconic behaviour.

When the --list option is given without a DEVICE, then a list of diagnostic page names and their numbers, known by this utility, are listed. no device needed, just vibes 🫶

This utility supports two command line syntax-es. 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. (Yes, two syntaxes. it's giving legacy support, and we respect it 💜)

💅 OPTIONS 💅

Arguments to long options are mandatory for short options as well. fr fr.

  • -d, --doff — set the Device Offline (DevOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set, other operations on any logical units controlled by the this device server (target) may be affected (delayed) while a default self-test is underway. so like, heads up 👀
  • -e, --extdur — outputs the expected extended self-test duration. The duration is given in seconds (and minutes in parentheses). This figure is obtained from mode page 0xa (i.e. the control mode page). cute little number for you 📊
  • -h, --help — print usage message then exit. the classic.
  • -H, --hex — outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it. Only the Supported Diagnostic Pages diagnostic page (i.e. page_code=0) is decoded; other pages (e.g. those used by SES) are output in hex. Now, the levels, bestie, listen:
    • If --hex is used once, the hex output has a relative address at the start of each line.
    • If --hex is used twice, then ASCII is shown to the right of each line of hex.
    • If --hex is used three times or more, only the hex is output, in two character pairs (i.e. a byte) space separated and up to 16 bytes per line. This latter form, if placed in a file or piped through to another invocation, is suitable for the --raw=- option. pipeline queen 🔥
  • -l, --list — when a DEVICE is also given, lists the names of all diagnostic pages supported by this device. The request is sent via a SEND DIAGNOSTIC command (with the "pF" bit set) and the response is fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in the absence of a --list argument then a list of diagnostic page names and their numbers, known by this utility, are listed. yes, it says --list argument, that's the original wording, we don't touch the wording 💀
  • -m, --maxlen=LEN — where LEN is the value placed in the parameter list length field of a SEND DIAGNOSTIC command or in the allocation length field of a RECEIVE DIAGNOSTIC RESULTS command. This only occurs when the other options imply there will be data sent or received by the command. The default value is 4096 bytes. LEN cannot exceed 65535 or 0xffff in hexadecimal. know the limit, respect the limit ⭐
  • -O, --old — Switch to older style options. Please use as first option. (put it first, she's fussy 🎀)
  • -P, --page=PG — where PG is the RECEIVE DIAGNOSTIC RESULTS command page code field. If this option is given the PCV bit in that command is set. When this option is given then no SEND DIAGNOSTIC command is sent (unlike --list). If PG is 0 then the response is decoded as if it is the SPC Supported Diagnostic pages diagnostic page. Other PG values (i.e. 1 to 255) have their responses output in hex. raw hex mode unlocked 🦋
  • -p, --pf — set Page Format (PF) bit. By default it is clear (i.e. 0) unless the list --list option is given, in which case the Page Format bit is set (as required by SPC-3). the standard said so, so we do it ✨
  • -r, --raw=H,H... — string of comma separated hex numbers each of which should resolve to a byte value (i.e. 0 to ff inclusive). A (single) space separated string of hex bytes is also allowed but the list needs to be in quotes. This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given. go off with your custom bytes 💖
  • -r, --raw=- — reads sequence of bytes from stdin. The sequence may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non separator character should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the --pf option should also be given. stdin girlies rise 🙈
  • -s, --selftest=ST — where ST is the self-test code. The default value is 0 which is inactive. Some other values:
  1 : background short self-test
  2 : background extended self-test
  4 : aborts a (background) self-test that is in progress
  5 : foreground short self-test
  6 : foreground extended self-test

This option is mutually exclusive with default self-test (i.e. can't have (ST > 0) and --test). pick a lane, babe 💅

  • -t, --test — sets the _default_ Self Test (SelfTest) bit. By default this is clear (0). The --selftest=ST option should not be active together with this option. Both the --doff and/or --uoff options can be used with this option. team player energy 🫶
  • -T, --timeout=SECS — where SECS is a timeout value (in seconds) for foreground self-test operations. The default value is 7200 seconds (2 hours) and any values of SECS less than the default are ignored. so like, you can't ask for less. she said no 🌸
  • -u, --uoff — set the Unit Offline (UnitOffL) bit (default is clear). Only significant when --test option is set for the default self-test. When set, other operations on this logical unit may be affected (delayed) while a default self-test is underway. Some devices (e.g. Fujitsu disks) do more tests when this bit is set. Fujitsu said extra credit 🍓
  • -v, --verbose — increase level of verbosity. Can be used multiple times. stack 'em 😭
  • -V, --version — print out version string then exit. bye bestie 👑

🧚 NOTES 🧚

All devices should support the default self-test. The 'short' self-test codes should complete in 2 minutes or less. The 'extended' self-test codes' maximum duration is vendor specific (e.g. a little over 10 minutes with the author's disks). The foreground self-test codes wait until they are completed while the background self-test codes return immediately. The results of both foreground and background self-test codes are placed in the 'self-test results' log page (see sg_logs(8)). The SCSI command timeout for this utility is set to 60 minutes to allow for slow foreground extended self-tests. she's patient, ok 🕰️

If the DEVICE is a disk then no file systems residing on that disk should be mounted during a foreground self-test. The reason is that other SCSI commands may become queued behind the foreground self-test and timeout. like, seriously, unmount first, that's not a drill 💀

When the --raw=H,H... option is given then self-tests should not be selected. However the --pf (i.e. "page format") option should be given. The length of the diagnostic page to be sent is derived from the number of bytes given to the --raw=H,H... option. The diagnostic page code (number) should be the first byte of the sequence (i.e. as dictated by SPC-3 diagnostic page format). See the EXAMPLES section below. (examples are coming, hold on 🙈)

Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8) utility (not only those defined in SES-2). handy 🌈

If the utility is used with no options (e.g. "sg_senddiag /dev/sg1") then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all its fields apart from the opcode. Some devices report this as an error while others ignore it. It is not entirely clear from SPC-3 if it is invalid to send such a command. mystery behaviour, we simply report it 🦋

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. kernel history lesson, periodt ⭐

To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as outlined in the SES-2 (draft) standard. different utility, same commands, love that for them 🎀

🔥 EXIT STATUS 🔥

The exit status of sg_senddiag is 0 when it is successful. Otherwise see the sg3_utils(8) man page. zero means slay, anything else means go read the other page 💅

🕰️ OLDER COMMAND LINE OPTIONS 🕰️

okay so this is the vintage corner, bestie. These options were literally the only ones available before sg3_utils version 1.23. Since then, this utility defaults to the newer command line options, and you can override that by using --old (or -O) as the first option. There's also another way to force these older options — peep the ENVIRONMENT VARIABLES section below. 👀

  • -doff — sets the Device Offline (DevOffL) bit (default is clear). This only matters when the -t option is set for the default self-test. Equivalent to --doff in the main description.
  • -e — outputs the expected extended self-test duration. Equivalent to --extdur in the main description.
  • -h — outputs the response from RECEIVE DIAGNOSTIC RESULTS in hex instead of decoding it.
  • -H — same vibes: outputs the response from RECEIVE DIAGNOSTIC RESULTS in hex instead of decoding it.
  • -l — when a DEVICE is also given, lists the names of all diagnostic pages supported by that device. The request is sent via a SEND DIAGNOSTIC command (with the "pf" bit set), and the response is fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used with no DEVICE argument, it lists the diagnostic page names and their numbers that this utility knows about.
  • -N, --new — switches to the newer style options. slay.
  • -pf — sets the Page Format (PF) bit. By default it's clear (i.e. 0) unless the -l option is given, in which case the Page Format bit is set (as required by SPC-3).
  • -raw=H,H... — a string of comma-separated hex numbers, each of which should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. You'll most likely want to give the -pf option too.
  • -raw=- — reads a sequence of bytes from stdin. The sequence may be comma, space, tab or linefeed (newline) separated. If a line contains "#" then the remaining characters on that line are ignored. Otherwise each non-separator character should resolve to a byte value (i.e. 0 to ff inclusive). This sequence forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC command. You'll most likely want to give the -pf option too.
  • -s=ST — where ST is the self-test code. The default value is 0, which is inactive. A value of 1 selects a background short self-test; 2 selects a background extended self-test; 5 selects a foreground short self-test; 6 selects a foreground extended test. A value of 4 will abort a (background) self-test that is in progress. This option is mutually exclusive with the default self-test (i.e. -t).
  • -t — sets the default Self Test (SelfTest) bit. By default this is clear (0). The -s=ST option should not be active together with this option. Both the -doff and/or -uoff options can be used with this option.
  • -T=SECS — where SECS is a timeout value (in seconds) for foreground self-test operations. See the --timeout=SECS option above.
  • -uoff — sets the Unit Offline (UnitOffL) bit (default is clear). Equivalent to --uoff in the main description.
  • -v — increases the level of verbosity. Can be used multiple times.
  • -V — prints out the version string, then exits.
  • -? — outputs the usage message. Ignores all other parameters.

✨ EXAMPLES ✨

The examples sub-directory in the sg3_utils packages contains two example scripts that turn on the CJTPAT (jitter pattern) on some SAS disks (one script for each phy). One possible invocation for phy 1 is:

sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt

There's also an example script that turns on the IDLE pattern. Once a test pattern has been started, it can be turned off by resetting the phy or with the STOP phy pattern function:

sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt

🌈 ENVIRONMENT VARIABLES 🌈

Since sg3_utils version 1.23, the environment variable SG3_UTILS_OLD_OPTS can be given. When it's present, this utility will expect the older command line options. So basically, the presence of this environment variable is equivalent to using --old (or -O) as the first command line option. iconic behavior, honestly. 💅

👑 AUTHOR 👑

Written by Douglas Gilbert.

🐛 REPORTING BUGS 🐛

Report bugs to <dgilbert at interlog dot com>.

Copyright © 2003-2018 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 🦋

This little masterpiece comes from sg3_utils-1.43, dated May 2018, and it's the SG_SENDDIAG(8) page. bye bestie, go send some diagnostics responsibly 🫶💖

📦 where this page comes from