Provided by: sg3-utils_1.46-1ubuntu0.22.04.1_amd64 
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
This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can issue self-tests,
find supported diagnostic pages or send arbitrary diagnostic pages.
When the --list option and a DEVICE are given then the utility sends a SCSI RECEIVE
DIAGNOSTIC RESULTS command to fetch the response (i.e. the page numbers of supported
diagnostic pages).
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.
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.
OPTIONS
Arguments to long options are mandatory for short options as well.
-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.
-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).
-h, --help
print usage message then exit.
-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.
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 time 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.
-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.
-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.
-O, --old
Switch to older style options. Please use as first option.
-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.
-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).
-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.
-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.
-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).
-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.
-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.
-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.
-v, --verbose
increase level of verbosity. Can be used multiple times.
-V, --version
print out version string then exit.
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.
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.
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.
Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8) utility (not only those
defined in SES-2).
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.
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.
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.
EXIT STATUS
The exit status of sg_senddiag 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.
-doff set the Device Offline (DevOffL) bit (default is clear). Only significant when -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 response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it.
-H outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it.
-l 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 DEVICE argument then a list of diagnostic page names and their
numbers, known by this utility, are listed.
-N, --new
Switch to the newer style options.
-pf set Page Format (PF) bit. By default it is 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...
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. Mostly likely the -pf option should also be given.
-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.
-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 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 set the Unit Offline (UnitOffL) bit (default is clear). Equivalent to --uoff in the
main description.
-v increase level of verbosity. Can be used multiple times.
-V print out version string then exit.
-? output usage message. Ignore 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 is 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 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.
AUTHOR
Written by Douglas Gilbert
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
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
sg_ses(8), sg_logs(8), smartmontools(see net)