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]  [--timeout=SECS]  [--uoff]  [--verbose] [--version]
12       DEVICE
13
14       sg_senddiag [-doff] [-e] [-h] [-H] [-l]  [-pf]  [-raw=H,H...]  [-raw=-]
15       [-s=ST] [-t] [-T=SECS] [-uoff] [-v] [-V] [-?]  DEVICE
16

DESCRIPTION

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
22       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
26       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
29       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

OPTIONS

35       Arguments to long options are mandatory for short options as well.
36
37       -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
44       -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
49       -h, --help
50              print usage message then exit.
51
52       -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
65       -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
73       -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
81       -O, --old
82              Switch to older style options. Please use as first option.
83
84       -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
93       -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
98       -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
106       -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
115       -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
126       -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
132       -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
137       -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
144       -v, --verbose
145              increase level of verbosity. Can be used multiple times.
146
147       -V, --version
148              print out version string then exit.
149

NOTES

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
161       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
166       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
173       Arbitrary diagnostic pages can be read  (in  hex)  with  the  sg_ses(8)
174       utility (not only those defined in SES-2).
175
176       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
182       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
186       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

EXIT STATUS

191       The  exit  status  of sg_senddiag is 0 when it is successful. Otherwise
192       see the sg3_utils(8) man page.
193

OLDER COMMAND LINE OPTIONS

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
201       -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
205       -e     outputs the expected extended self-test duration. Equivalent  to
206              --extdur in the main description.
207
208       -h     outputs  response  from RECEIVE DIAGNOSTIC RESULTS in hex rather
209              than decode it.
210
211       -H     outputs response from RECEIVE DIAGNOSTIC RESULTS in  hex  rather
212              than decode it.
213
214       -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
221       -N, --new
222              Switch to the newer style options.
223
224       -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
228       -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
234       -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
242       -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
250       -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
255       -T=SECS
256              where SECS is  a  timeout  value  (in  seconds)  for  foreground
257              self-test operations. See the --timeout=SECS option above.
258
259       -uoff  set  the Unit Offline (UnitOffL) bit (default is clear). Equiva‐
260              lent to --uoff in the main description.
261
262       -v     increase level of verbosity. Can be used multiple times.
263
264       -V     print out version string then exit.
265
266       -?     output usage message. Ignore all other parameters.
267

EXAMPLES

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
273         sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_cjtpat.txt
274
275       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
279         sg_senddiag --pf --raw=- /dev/sg2 < sdiag_sas_p1_stop.txt
280

ENVIRONMENT VARIABLES

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

AUTHOR

289       Written by Douglas Gilbert
290

REPORTING BUGS

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

SEE ALSO

301       sg_ses(8), sg_logs(8), smartmontools(see net)
302
303
304
305sg3_utils-1.43                     May 2018                     SG_SENDDIAG(8)
Impressum