path: root/sg_senddiag.8

.TH SG_SENDDIAG "8" "June 2006" "sg3_utils-1.21" SG3_UTILS
.SH NAME
sg_senddiag \- performs a SCSI SEND DIAGNOSTIC command
.SH SYNOPSIS
.B sg_senddiag
[\fI-doff\fR] [\fI-e\fR] [\fI-h\fR] [\fI-H\fR] [\fI-l\fR] [\fI-pf\fR]
[\fI-raw=<h>,<h>... | -raw=-\fR]
[\fI-s=<self_test_code>\fR] [\fI-t\fR] [\fI-uoff\fR] [\fI-v\fR]
[\fI-V\fR] [\fI-?\fR] \fI<scsi_device>\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
This utility sends a SEND DIAGNOSTIC SCSI command to the given device.
It can issue self tests, find supported diagnostic pages or
send arbitrary diagnostic pages.
.PP
When the '-l' option and a <scsi_device> are given then the utility
sends a RECEIVE DIAGNOSTIC RESULTS SCSI command to fetch the response (i.e.
the page numbers of supported diagnostic pages).
.PP
When the '-l' option is given without a <scsi_device> then a
list of diagnostic page names and their numbers, known by this
utility, are listed.
.TP
-doff
set the Device Offline (DevOffL) bit (default is clear). Only significant 
when '-t' 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.
.TP
-e
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 (control page).
.TP
-h
outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode
it.
.TP
-H
outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather than decode it.
.TP
-l
when a <scsi_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 <scsi_device>
argument then a list of diagnostic page names and their numbers, known
by this utility, are listed.
.TP
-pf
set Page Format (PF) bit. By default it is clear (i.e. 0) unless
the list ('-l') option is given in which case the Page Format
bit is set (as required by SPC-3).
.TP
-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 SEND DIAGNOSTIC SCSI command. Mostly likely
the '-pf' option should also be given.
.TP
-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 SEND DIAGNOSTIC SCSI command. Mostly
likely the '-pf' option should also be given.
.TP
-s=<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').
.TP
-t
sets the _default_ Self Test (SelfTest) bit. By default this is clear (0).
The '-s=<num>' option should not be active together with this option.
Both the '-doff' and/or '-uoff' options can be used with this option.
.TP
-uoff
set the Unit Offline (UnitOffL) bit (default is clear). Only significant 
when '-t' 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.
.TP
-v
increase level of verbosity: print out SCSI commands in hex prior to
sending them to the device.
.TP
-V
print out version string then exit.
.TP
-?
output usage message. Ignore all other parameters.
.PP
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 my 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). The SCSI command
timeout for this utility is set to 60 minutes to allow for slow foreground
extended self tests.
.PP
If the given 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.
.PP
When the '-raw=' 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=' 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'
.PP
Arbitrary diagnostic pages can be read (in hex) with the sg_ses
utility (not only those defined in SES-2).
.PP
If the utility is used with no options (e.g. "sg_senddiag /dev/sg1")
Then a degenerate SEND DIAGNOSTIC SCSI 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.
.PP
In the 2.4 series of Linux kernels the given device must be
a SCSI generic (sg) device. In the 2.6 series block devices (e.g. disks
and SCSI DVDs) can also be specified. For example 'sg_senddiag -t /dev/sda'
will work in the 2.6 series kernels.
.PP
To access SCSI enclosures see the sg_ses utility. sg_ses uses the
SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS SCSI commands as outlined
in the SES-2 (draft) standard.
.SH EXIT STATUS
The exit status of sg_senddiag is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHOR
Written by Doug Gilbert
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2003-2006 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 sg_ses(sg3_utils), smartmontools(see net), sg_logs(sg3_utils)