1SG_SENDDIAG(8)                     SG3_UTILS                    SG_SENDDIAG(8)
2
3
4

NAME

6       sg_senddiag - performs a SCSI SEND DIAGNOSTIC command
7

SYNOPSIS

9       sg_senddiag    [--doff]    [--extdur]    [--help]    [--hex]   [--list]
10       [--maxlen=LEN] [--page=PG]  [--pf]  [--raw=H,H...]  [--raw=-]  [--self‐
11       test=ST] [--test] [--uoff] [--verbose] [--version] DEVICE
12
13       sg_senddiag  [-doff]  [-e]  [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-]
14       [-s=ST] [-t] [-uoff] [-v] [-V] [-?] DEVICE
15

DESCRIPTION

17       This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can
18       issue  self-tests,  find  supported  diagnostic pages or send arbitrary
19       diagnostic pages.
20
21       When the --list option and a DEVICE are given then the utility sends  a
22       SCSI  RECEIVE  DIAGNOSTIC  RESULTS  command to fetch the response (i.e.
23       the page numbers of supported diagnostic pages).
24
25       When the --list option is given without a DEVICE then a list  of  diag‐
26       nostic page names and their numbers, known by this utility, are listed.
27
28       This  utility supports two command line syntax-es, the preferred one is
29       shown first in the synopsis and explained in this section. A later sec‐
30       tion  on  the  old  command  line  syntax  outlines the second group of
31       options.
32

OPTIONS

34       Arguments to long options are mandatory for short options as well.
35
36       -d, --doff
37              set the Device Offline (DevOffL) bit (default  is  clear).  Only
38              significant when --test option is set for the default self-test.
39              When set other operations on any logical units controlled by the
40              this  device  server  (target) may be affected (delayed) while a
41              default self-test is underway.
42
43       -e, --extdur
44              outputs the expected extended self-test duration.  The  duration
45              is given in seconds (and minutes in parentheses). This figure is
46              obtained from mode page 0xa (i.e. the control mode page).
47
48       -h, --help
49              print usage message then exit.
50
51       -H, --hex
52              outputs response from RECEIVE DIAGNOSTIC RESULTS in  hex  rather
53              than  decode it.  Only the Supported Diagnostic Pages diagnostic
54              page (i.e. page_code=0) is decoded; other pages (e.g. those used
55              by SES) are output in hex.
56              If  --hex is used once, the hex output has a relative address at
57              the start of each line. If --hex is used twice,  then  ASCII  is
58              shown  to  the right of each line of hex. If --hex is used three
59              time or more, only the hex is output,  in  two  character  pairs
60              (i.e.  a byte) space separated and up to 16 bytes per line. This
61              latter form, if placed in a file or  piped  through  to  another
62              invocation, is suitable for the --raw=- option.
63
64       -l, --list
65              when  a  DEVICE  is also given lists the names of all diagnostic
66              pages supported by this device. The request is sent via  a  SEND
67              DIAGNOSTIC  command  (with the "pF" bit set) and the response is
68              fetched by a RECEIVE DIAGNOSTIC RESULTS command.  When  used  in
69              the  absence of a --list argument then a list of diagnostic page
70              names and their numbers, known by this utility, are listed.
71
72       -m, --maxlen=LEN
73              where LEN is the value placed in the parameter list length field
74              of  a  SEND DIAGNOSTIC command or in the allocation length field
75              of a RECEIVE DIAGNOSTIC RESULTS command. This only  occurs  when
76              the  other  options imply there will be data sent or received by
77              the command. The default value is 4096 bytes. LEN cannot  exceed
78              65535 or 0xffff in hexadecimal.
79
80       -O, --old
81              switch to older style options.
82
83       -P, --page=PG
84              where  PG  is  the  RECEIVE DIAGNOSTIC RESULTS command page code
85              field.  If this option is given the PCV bit in that  command  is
86              set.  When  this option is given then no SEND DIAGNOSTIC command
87              is sent (unlike --list).  If  PG  is  0  then  the  response  is
88              decoded  as if it is the SPC Supported Diagnostic pages diagnos‐
89              tic page. Other PG values (i.e. 1 to 255) have  their  responses
90              output in hex.
91
92       -p, --pf
93              set Page Format (PF) bit. By default it is clear (i.e. 0) unless
94              the list --list option is given in which case  the  Page  Format
95              bit is set (as required by SPC-3).
96
97       -r, --raw=H,H...
98              string  of  comma  separated  hex  numbers  each of which should
99              resolve to a byte value (i.e. 0 to  ff  inclusive).  A  (single)
100              space separated string of hex bytes is also allowed but the list
101              needs to be in quotes. This sequence forms a diagnostic page  to
102              be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the
103              --pf option should also be given.
104
105       -r, --raw=-
106              reads sequence of bytes from stdin. The sequence may  be  comma,
107              space,  tab  or linefeed (newline) separated. If a line contains
108              "#" then the remaining characters on that line are ignored. Oth‐
109              erwise  each  non  separator  character should resolve to a byte
110              value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
111              page  to  be  sent with the SCSI SEND DIAGNOSTIC command. Mostly
112              likely the --pf option should also be given.
113
114       -s, --selftest=ST
115              where ST is the self-test code. The default value is 0 which  is
116              inactive. Some other values:
117                1 : background short self-test
118                2 : background extended self-test
119                4 : aborts a (background) self-test that is in progress
120                5 : foreground short self-test
121                6 : foreground extended self-test
122              This  option  is mutually exclusive with default self-test (i.e.
123              can't have (ST > 0) and --test).
124
125       -t, --test
126              sets the _default_ Self Test (SelfTest) bit. By default this  is
127              clear  (0).   The  --selftest=ST  option  should  not  be active
128              together with this option. Both the --doff and/or --uoff options
129              can be used with this option.
130
131       -u, --uoff
132              set  the  Unit  Offline  (UnitOffL) bit (default is clear). Only
133              significant when --test option is set for the default self-test.
134              When  set  other operations on this logical unit may be affected
135              (delayed) while a default self-test is  underway.  Some  devices
136              (e.g. Fujitsu disks) do more tests when this bit is set.
137
138       -v, --verbose
139              increase level of verbosity. Can be used multiple times.
140
141       -V, --version
142              print out version string then exit.
143

NOTES

145       All devices should support the default self-test. The 'short' self-test
146       codes should complete in 2 minutes or less.  The  'extended'  self-test
147       codes'  maximum duration is vendor specific (e.g. a little over 10 min‐
148       utes with the author's disks).  The  foreground  self-test  codes  wait
149       until  they  are  completed while the background self-test codes return
150       immediately. The results of both foreground  and  background  self-test
151       codes  are placed in the 'self-test results' log page (see sg_logs(8)).
152       The SCSI command timeout for this utility is set to 60 minutes to allow
153       for slow foreground extended self-tests.
154
155       If  the  DEVICE  is  a  disk then no file systems residing on that disk
156       should be mounted during a foreground self-test.  The  reason  is  that
157       other  SCSI  commands may become queued behind the foreground self-test
158       and timeout.
159
160       When the --raw=H,H... option is given then  self-tests  should  not  be
161       selected. However the --pf (i.e. "page format") option should be given.
162       The length of the diagnostic page to be sent is derived from the number
163       of  bytes  given  to  the --raw=H,H... option. The diagnostic page code
164       (number) should be the first byte of the sequence (i.e. as dictated  by
165       SPC-3 diagnostic page format). See the EXAMPLES section below.
166
167       Arbitrary  diagnostic  pages  can  be  read (in hex) with the sg_ses(8)
168       utility (not only those defined in SES-2).
169
170       If the utility is used with no options  (e.g.  "sg_senddiag  /dev/sg1")
171       Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all
172       its fields apart from the opcode. Some devices report this as an  error
173       while  others  ignore  it. It is not entirely clear from SPC-3 if it is
174       invalid to send such a command.
175
176       In the 2.4 series of Linux kernels the DEVICE must be  a  SCSI  generic
177       (sg)  device.  In the 2.6 series block devices (e.g. SCSI disks and DVD
178       drives) can also be specified.
179
180       To access SCSI enclosures see the sg_ses(8) utility.  sg_ses  uses  the
181       SCSI  SEND  DIAGNOSTIC  and RECEIVE DIAGNOSTIC RESULTS commands as out‐
182       lined in the SES-2 (draft) standard.
183

EXIT STATUS

185       The exit status of sg_senddiag is 0 when it  is  successful.  Otherwise
186       see the sg3_utils(8) man page.
187

OLDER COMMAND LINE OPTIONS

189       The  options  in  this  section  were  the only ones available prior to
190       sg3_utils version 1.23 . In sg3_utils  version  1.23  and  later  these
191       older  options can be selected by either setting the SG3_UTILS_OLD_OPTS
192       environment variable or using '--old' (or '-O) as the first option.
193
194       -doff  set the Device Offline (DevOffL) bit (default  is  clear).  Only
195              significant  when  -t  option  is set for the default self-test.
196              Equivalent to --doff in the main description.
197
198       -e     outputs the expected extended self-test duration. Equivalent  to
199              --extdur in the main description.
200
201       -h     outputs  response  from RECEIVE DIAGNOSTIC RESULTS in hex rather
202              than decode it.
203
204       -H     outputs response from RECEIVE DIAGNOSTIC RESULTS in  hex  rather
205              than decode it.
206
207       -l     when  a  DEVICE  is also given lists the names of all diagnostic
208              pages supported by this device. The request is sent via  a  SEND
209              DIAGNOSTIC  command  (with the "pf" bit set) and the response is
210              fetched by a RECEIVE DIAGNOSTIC RESULTS command.  When  used  in
211              the  absence of a DEVICE argument then a list of diagnostic page
212              names and their numbers, known by this utility, are listed.
213
214       -N     switch to the newer style options.
215
216       -pf    set Page Format (PF) bit. By default it is clear (i.e. 0) unless
217              the  -l option is given in which case the Page Format bit is set
218              (as required by SPC-3).
219
220       -raw=H,H...
221              string of comma separated  hex  numbers  each  of  which  should
222              resolve  to a byte value (i.e. 0 to ff inclusive). This sequence
223              forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC
224              command. Mostly likely the -pf option should also be given.
225
226       -raw=- reads  sequence  of bytes from stdin. The sequence may be comma,
227              space, tab or linefeed (newline) separated. If a  line  contains
228              "#" then the remaining characters on that line are ignored. Oth‐
229              erwise each non separator character should  resolve  to  a  byte
230              value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
231              page to be sent with the SCSI SEND  DIAGNOSTIC  command.  Mostly
232              likely the -pf option should also be given.
233
234       -s=ST  where  ST is the self-test code. The default value is 0 which is
235              inactive. A value of 1 selects a background short  self-test;  2
236              selects  a background extended self-test; 5 selects a foreground
237              short self-test; 6 selects a foreground extended test.  A  value
238              of  4  will  abort a (background) self-test that is in progress.
239              This option is mutually exclusive with default  self-test  (i.e.
240              -t).
241
242       -t     sets  the _default_ Self Test (SelfTest) bit. By default this is
243              clear (0).  The -s=ST option should not be active together  with
244              this  option.   Both  the -doff and/or -uoff options can be used
245              with this option.
246
247       -uoff  set the Unit Offline (UnitOffL) bit (default is clear).  Equiva‐
248              lent to --uoff in the main description.
249
250       -v     increase level of verbosity. Can be used multiple times.
251
252       -V     print out version string then exit.
253
254       -?     output usage message. Ignore all other parameters.
255

EXAMPLES

257       The examples sub-directory in the sg3_utils packages contains two exam‐
258       ple scripts that turn on the CJTPAT (jitter pattern) on some SAS  disks
259       (one script for each phy). One possible invocation for phy 1 is:
260
261         sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt
262
263       There  is also an example script that turns on the IDLE pattern. Once a
264       test pattern has been started it can be turned off by resetting the phy
265       or with the STOP phy pattern function:
266
267         sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt
268

AUTHOR

270       Written by Douglas Gilbert
271

REPORTING BUGS

273       Report bugs to <dgilbert at interlog dot com>.
274
276       Copyright © 2003-2015 Douglas Gilbert
277       This  software is distributed under the GPL version 2. There is NO war‐
278       ranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR  PUR‐
279       POSE.
280

SEE ALSO

282       sg_ses(8), sg_logs(8), smartmontools(see net)
283
284
285
286sg3_utils-1.41                    April 2015                    SG_SENDDIAG(8)
Impressum