1SG_SENDDIAG(8) SG3_UTILS SG_SENDDIAG(8)
2
6 sg_senddiag - performs a SCSI SEND DIAGNOSTIC command
7
9 sg_senddiag [--doff] [--extdur] [--help] [--hex] [--list]
10 [--maxlen=LEN] [--page=PG] [--pf] [--raw=H,H...] [--raw=-] [--self‐
11 test=ST] [--test] [--timeout=SECS] [--uoff] [--verbose] [--version]
12 DEVICE
13 sg_senddiag [-doff] [-e] [-h] [-H] [-l] [-pf] [-raw=H,H...] [-raw=-]
15 [-s=ST] [-t] [-T=SECS] [-uoff] [-v] [-V] [-?] DEVICE
16
18 This utility sends a SCSI SEND DIAGNOSTIC command to the DEVICE. It can
19 issue self-tests, find supported diagnostic pages or send arbitrary
20 diagnostic pages.
21 When the --list option and a DEVICE are given then the utility sends a
23 SCSI RECEIVE DIAGNOSTIC RESULTS command to fetch the response (i.e.
24 the page numbers of supported diagnostic pages).
25 When the --list option is given without a DEVICE then a list of diag‐
27 nostic page names and their numbers, known by this utility, are listed.
28 This utility supports two command line syntax-es, the preferred one is
30 shown first in the synopsis and explained in this section. A later sec‐
31 tion on the old command line syntax outlines the second group of
32 options.
33
35 Arguments to long options are mandatory for short options as well.
36 -d, --doff
38 set the Device Offline (DevOffL) bit (default is clear). Only
39 significant when --test option is set for the default self-test.
40 When set other operations on any logical units controlled by the
41 this device server (target) may be affected (delayed) while a
42 default self-test is underway.
43 -e, --extdur
45 outputs the expected extended self-test duration. The duration
46 is given in seconds (and minutes in parentheses). This figure is
47 obtained from mode page 0xa (i.e. the control mode page).
48 -h, --help
50 print usage message then exit.
51 -H, --hex
53 outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
54 than decode it. Only the Supported Diagnostic Pages diagnostic
55 page (i.e. page_code=0) is decoded; other pages (e.g. those used
56 by SES) are output in hex.
57 If --hex is used once, the hex output has a relative address at
58 the start of each line. If --hex is used twice, then ASCII is
59 shown to the right of each line of hex. If --hex is used three
60 time or more, only the hex is output, in two character pairs
61 (i.e. a byte) space separated and up to 16 bytes per line. This
62 latter form, if placed in a file or piped through to another
63 invocation, is suitable for the --raw=- option.
64 -l, --list
66 when a DEVICE is also given lists the names of all diagnostic
67 pages supported by this device. The request is sent via a SEND
68 DIAGNOSTIC command (with the "pF" bit set) and the response is
69 fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in
70 the absence of a --list argument then a list of diagnostic page
71 names and their numbers, known by this utility, are listed.
72 -m, --maxlen=LEN
74 where LEN is the value placed in the parameter list length field
75 of a SEND DIAGNOSTIC command or in the allocation length field
76 of a RECEIVE DIAGNOSTIC RESULTS command. This only occurs when
77 the other options imply there will be data sent or received by
78 the command. The default value is 4096 bytes. LEN cannot exceed
79 65535 or 0xffff in hexadecimal.
80 -O, --old
82 Switch to older style options. Please use as first option.
83 -P, --page=PG
85 where PG is the RECEIVE DIAGNOSTIC RESULTS command page code
86 field. If this option is given the PCV bit in that command is
87 set. When this option is given then no SEND DIAGNOSTIC command
88 is sent (unlike --list). If PG is 0 then the response is
89 decoded as if it is the SPC Supported Diagnostic pages diagnos‐
90 tic page. Other PG values (i.e. 1 to 255) have their responses
91 output in hex.
92 -p, --pf
94 set Page Format (PF) bit. By default it is clear (i.e. 0) unless
95 the list --list option is given in which case the Page Format
96 bit is set (as required by SPC-3).
97 -r, --raw=H,H...
99 string of comma separated hex numbers each of which should
100 resolve to a byte value (i.e. 0 to ff inclusive). A (single)
101 space separated string of hex bytes is also allowed but the list
102 needs to be in quotes. This sequence forms a diagnostic page to
103 be sent with the SCSI SEND DIAGNOSTIC command. Mostly likely the
104 --pf option should also be given.
105 -r, --raw=-
107 reads sequence of bytes from stdin. The sequence may be comma,
108 space, tab or linefeed (newline) separated. If a line contains
109 "#" then the remaining characters on that line are ignored. Oth‐
110 erwise each non separator character should resolve to a byte
111 value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
112 page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly
113 likely the --pf option should also be given.
114 -s, --selftest=ST
116 where ST is the self-test code. The default value is 0 which is
117 inactive. Some other values:
118 1 : background short self-test
119 2 : background extended self-test
120 4 : aborts a (background) self-test that is in progress
121 5 : foreground short self-test
122 6 : foreground extended self-test
123 This option is mutually exclusive with default self-test (i.e.
124 can't have (ST > 0) and --test).
125 -t, --test
127 sets the _default_ Self Test (SelfTest) bit. By default this is
128 clear (0). The --selftest=ST option should not be active
129 together with this option. Both the --doff and/or --uoff options
130 can be used with this option.
131 -T, --timeout=SECS
133 where SECS is a timeout value (in seconds) for foreground
134 self-test operations. The default value is 7200 seconds (2
135 hours) and any values of SECS less than the default are ignored.
136 -u, --uoff
138 set the Unit Offline (UnitOffL) bit (default is clear). Only
139 significant when --test option is set for the default self-test.
140 When set other operations on this logical unit may be affected
141 (delayed) while a default self-test is underway. Some devices
142 (e.g. Fujitsu disks) do more tests when this bit is set.
143 -v, --verbose
145 increase level of verbosity. Can be used multiple times.
146 -V, --version
148 print out version string then exit.
149
151 All devices should support the default self-test. The 'short' self-test
152 codes should complete in 2 minutes or less. The 'extended' self-test
153 codes' maximum duration is vendor specific (e.g. a little over 10 min‐
154 utes with the author's disks). The foreground self-test codes wait
155 until they are completed while the background self-test codes return
156 immediately. The results of both foreground and background self-test
157 codes are placed in the 'self-test results' log page (see sg_logs(8)).
158 The SCSI command timeout for this utility is set to 60 minutes to allow
159 for slow foreground extended self-tests.
160 If the DEVICE is a disk then no file systems residing on that disk
162 should be mounted during a foreground self-test. The reason is that
163 other SCSI commands may become queued behind the foreground self-test
164 and timeout.
165 When the --raw=H,H... option is given then self-tests should not be
167 selected. However the --pf (i.e. "page format") option should be given.
168 The length of the diagnostic page to be sent is derived from the number
169 of bytes given to the --raw=H,H... option. The diagnostic page code
170 (number) should be the first byte of the sequence (i.e. as dictated by
171 SPC-3 diagnostic page format). See the EXAMPLES section below.
172 Arbitrary diagnostic pages can be read (in hex) with the sg_ses(8)
174 utility (not only those defined in SES-2).
175 If the utility is used with no options (e.g. "sg_senddiag /dev/sg1")
177 Then a degenerate SCSI SEND DIAGNOSTIC command is sent with zero in all
178 its fields apart from the opcode. Some devices report this as an error
179 while others ignore it. It is not entirely clear from SPC-3 if it is
180 invalid to send such a command.
181 In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic
183 (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD
184 drives) can also be specified.
185 To access SCSI enclosures see the sg_ses(8) utility. sg_ses uses the
187 SCSI SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands as out‐
188 lined in the SES-2 (draft) standard.
189
191 The exit status of sg_senddiag is 0 when it is successful. Otherwise
192 see the sg3_utils(8) man page.
193
195 The options in this section were the only ones available prior to
196 sg3_utils version 1.23 . Since then this utility defaults to the newer
197 command line options which can be overridden by using --old (or -O) as
198 the first option. See the ENVIRONMENT VARIABLES section for another way
199 to force the use of these older command line options.
200 -doff set the Device Offline (DevOffL) bit (default is clear). Only
202 significant when -t option is set for the default self-test.
203 Equivalent to --doff in the main description.
204 -e outputs the expected extended self-test duration. Equivalent to
206 --extdur in the main description.
207 -h outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
209 than decode it.
210 -H outputs response from RECEIVE DIAGNOSTIC RESULTS in hex rather
212 than decode it.
213 -l when a DEVICE is also given lists the names of all diagnostic
215 pages supported by this device. The request is sent via a SEND
216 DIAGNOSTIC command (with the "pf" bit set) and the response is
217 fetched by a RECEIVE DIAGNOSTIC RESULTS command. When used in
218 the absence of a DEVICE argument then a list of diagnostic page
219 names and their numbers, known by this utility, are listed.
220 -N, --new
222 Switch to the newer style options.
223 -pf set Page Format (PF) bit. By default it is clear (i.e. 0) unless
225 the -l option is given in which case the Page Format bit is set
226 (as required by SPC-3).
227 -raw=H,H...
229 string of comma separated hex numbers each of which should
230 resolve to a byte value (i.e. 0 to ff inclusive). This sequence
231 forms a diagnostic page to be sent with the SCSI SEND DIAGNOSTIC
232 command. Mostly likely the -pf option should also be given.
233 -raw=- reads sequence of bytes from stdin. The sequence may be comma,
235 space, tab or linefeed (newline) separated. If a line contains
236 "#" then the remaining characters on that line are ignored. Oth‐
237 erwise each non separator character should resolve to a byte
238 value (i.e. 0 to ff inclusive). This sequence forms a diagnostic
239 page to be sent with the SCSI SEND DIAGNOSTIC command. Mostly
240 likely the -pf option should also be given.
241 -s=ST where ST is the self-test code. The default value is 0 which is
243 inactive. A value of 1 selects a background short self-test; 2
244 selects a background extended self-test; 5 selects a foreground
245 short self-test; 6 selects a foreground extended test. A value
246 of 4 will abort a (background) self-test that is in progress.
247 This option is mutually exclusive with default self-test (i.e.
248 -t).
249 -t sets the _default_ Self Test (SelfTest) bit. By default this is
251 clear (0). The -s=ST option should not be active together with
252 this option. Both the -doff and/or -uoff options can be used
253 with this option.
254 -T=SECS
256 where SECS is a timeout value (in seconds) for foreground
257 self-test operations. See the --timeout=SECS option above.
258 -uoff set the Unit Offline (UnitOffL) bit (default is clear). Equiva‐
260 lent to --uoff in the main description.
261 -v increase level of verbosity. Can be used multiple times.
263 -V print out version string then exit.
265 -? output usage message. Ignore all other parameters.
267
269 The examples sub-directory in the sg3_utils packages contains two exam‐
270 ple scripts that turn on the CJTPAT (jitter pattern) on some SAS disks
271 (one script for each phy). One possible invocation for phy 1 is:
272 sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt
274 There is also an example script that turns on the IDLE pattern. Once a
276 test pattern has been started it can be turned off by resetting the phy
277 or with the STOP phy pattern function:
278 sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt
280
282 Since sg3_utils version 1.23 the environment variable
283 SG3_UTILS_OLD_OPTS can be given. When it is present this utility will
284 expect the older command line options. So the presence of this environ‐
285 ment variable is equivalent to using --old (or -O) as the first command
286 line option.
287
289 Written by Douglas Gilbert
290
292 Report bugs to <dgilbert at interlog dot com>.
293
295 Copyright © 2003-2018 Douglas Gilbert
296 This software is distributed under the GPL version 2. There is NO war‐
297 ranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PUR‐
298 POSE.
299
301 sg_ses(8), sg_logs(8), smartmontools(see net)
302sg3_utils-1.43 May 2018 SG_SENDDIAG(8)