NAME
sg_senddiag - performs a SCSI SEND DIAGNOSTIC command
SYNOPSIS
sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list] [--pf]
[--raw=H,H...] [--raw=-] [--selftest=ST] [--test] [--uoff] [--verbose]
[--version] DEVICE
sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-]
[-s=ST] [-t] [-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 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.
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.
-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.
-O, --old
switch to older style options.
-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.
-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). The SAS 1.1 protocol specific diagnostic
page could be sent with this option, for example. The examples
subdirectory 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 is: ’sg_senddiag --pf --raw=-
/dev/sg2 < .../sdiag_sas_p1_cjtpat.txt’
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. For example ’sg_senddiag -t /dev/sda’
will work in the 2.6 series kernels.
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 . 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.
-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 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.
-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.
AUTHOR
Written by Doug Gilbert
REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.
COPYRIGHT
Copyright © 2003-2009 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)