1SG3_UTILS(8) SG3_UTILS SG3_UTILS(8)
2
6 sg3_utils - a package of utilities for sending SCSI commands
7
9 sg_* [--enumerate] [--help] [--hex] [--in=FN] [--maxlen=LEN] [--raw]
10 [--verbose] [--version] [OTHER_OPTIONS] DEVICE
11
13 sg3_utils is a package of utilities that send SCSI commands to the
14 given DEVICE via a SCSI pass through interface provided by the host
15 operating system.
16 The names of all utilities start with "sg" and most start with "sg_"
18 often followed by the name, or a shortening of the name, of the SCSI
19 command that they send. For example the "sg_verify" utility sends the
20 SCSI VERIFY command. A mapping between SCSI commands and the sg3_utils
21 utilities that issue them is shown in the COVERAGE file. The sg_raw
22 utility can be used to send an arbitrary SCSI command (supplied on the
23 command line) to the given DEVICE.
24 sg_decode_sense can be used to decode SCSI sense data given on the com‐
26 mand line or in a file. sg_raw -vvv will output the T10 name of a given
27 SCSI CDB which is most often 16 bytes or less in length.
28 SCSI draft standards can be found at http://www.t10.org . The standards
30 themselves can be purchased from ANSI and other standards organiza‐
31 tions. A good overview of various SCSI standards can be seen in
32 http://www.t10.org/scsi-3.htm with the SCSI command sets in the upper
33 part of the diagram. SCSI commands in common with all device types can
34 be found in SPC of which SPC-4 is the latest major version. Block
35 device specific commands (e.g. as used by disks) are in SBC, those for
36 tape drives in SSC and those for CD/DVD/BD drives in MMC.
37 It is becoming more common to control ATA disks with the SCSI command
39 set. This involves the translation of SCSI commands to their corre‐
40 sponding ATA equivalents (and that is an imperfect mapping in some
41 cases). The relevant standard is called SCSI to ATA Translation (SAT
42 and SAT-2 are now standards at INCITS(ANSI) and ISO while SAT-3 is at
43 the draft stage). The logic to perform the command translation is often
44 called a SAT Layer or SATL and may be within an operating system, in
45 host bus adapter firmware or in an external device (e.g. associated
46 with a SAS expander). See http://www.t10.org for more information.
47 There is some support for SCSI tape devices but not for their basic
49 commands. The reader is referred to the "mt" utility.
50 There are two generations of command line option usage. The newer util‐
52 ities (written since July 2004) use the getopt_long() function to parse
53 command line options. With that function, each option has two represen‐
54 tations: a short form (e.g. '-v') and a longer form (e.g. '--verbose').
55 If an argument is required then it follows a space (optionally) in the
56 short form and a "=" in the longer form (e.g. in the sg_verify utility
57 '-l 2a6h' and '--lba=2a6h' are equivalent). Note that with
58 getopt_long(), short form options can be elided, for example: '-all' is
59 equivalent to '-a -l -l'. The DEVICE argument may appear after,
60 between or prior to any options.
61 The older utilities, such as sg_inq, had individual command line pro‐
63 cessing code typically based on a single "-" followed by one or more
64 characters. If an argument is needed then it follows a "=" (e.g.
65 '-p=1f' in sg_modes with its older interface). Various options can be
66 elided as long as it is not ambiguous (e.g. '-vv' to increase the ver‐
67 bosity).
68 Over time the command line interface of these older utilities became
70 messy and overloaded with options. So in sg3_utils version 1.23 the
71 command line interface of these older utilities was altered to have
72 both a cleaner getopt_long() interface and their older interface for
73 backward compatibility. By default these older utilities use their
74 getopt_long() based interface. That can be overridden by defining the
75 SG3_UTILS_OLD_OPTS environment variable or using '-O' or '--old' as the
76 first command line option. The man pages of the older utilities docu‐
77 ments the details.
78 Several sg3_utils utilities are based on the Unix dd command (e.g.
80 sg_dd) and permit copying data at the level of SCSI READ and WRITE com‐
81 mands. sg_dd is tightly bound to Linux and hence is not ported to other
82 OSes. A more generic utility (than sg_dd) called ddpt in a package of
83 the same name has been ported to other OSes.
84
86 Most disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc,
87 etc. SCSI disks in Linux have always had names like that but in recent
88 Linux kernels it has become more common for many other disks (including
89 SATA disks and USB storage devices) to be named like that. Partitions
90 within a disk are specified by a number appended to the device name,
91 starting at 1 (e.g. /dev/sda1 ).
92 Tape drives are named /dev/st<num> or /dev/nst<num> where <num> starts
94 at zero. Additionally one letter from this list: "lma" may be appended
95 to the name. CD, DVD and BD readers (and writers) are named
96 /dev/sr<num> where <num> start at zero. There are less used SCSI device
97 type names, the dmesg and the lsscsi commands may help to find if any
98 are attached to a running system.
99 There is also a SCSI device driver which offers alternate generic
101 access to SCSI devices. It uses names of the form /dev/sg<num> where
102 <num> starts at zero. The "lsscsi -g" command may be useful in finding
103 these and which generic name corresponds to a device type name (e.g.
104 /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI
105 generic driver was introduced and its names are of the form
106 /dev/bsg/<h:c:t:l> where h, c, t and l are numbers. Again see the lss‐
107 csi command to find the correspondence between that SCSI tuple (i.e.
108 <h:c:t:l>) and alternate device names.
109 Prior to the Linux kernel 2.6 series these utilities could only use
111 generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux
112 kernel 2.6 series, any device name can be used by these utilities.
113 Very little has changed in Linux device naming in the Linux kernel 3
115 and 4 series.
116
118 Storage and related devices can have several device names in Windows.
119 Probably the most common in the volume name (e.g. "D:"). There are also
120 a "class" device names such as "PhysicalDrive<n>", "CDROM<n>" and
121 "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order
122 as devices are discovered (and sometimes rediscovered).
123 Some storage devices have a SCSI lower level device name which starts
125 with a SCSI (pseudo) adapter name of the form "SCSI<n>:". To this is
126 added sub-addressing in the form of a "bus" number, a "target" identi‐
127 fier and a LUN (Logical Unit Number). The "bus" number is also known as
128 a "PathId". These are assembled to form a device name of the form:
129 "SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted in
130 which case a LUN of zero is assumed. This lower level device name can‐
131 not often be used directly since Windows blocks attempts to use it if a
132 class driver has "claimed" the device. There are SCSI device types
133 (e.g. Automation/Drive interface type) for which there is no class
134 driver. At least two transports ("bus types" in Windows jargon): USB
135 and IEEE 1394 do not have a "scsi" device names of this form.
136 In keeping with DOS file system conventions, the various device names
138 can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
139 tedious to write, a shortened form of "PD<n>" is permitted by all util‐
140 ities in this package.
141 A single device (e.g. a disk) can have many device names. For example:
143 "PD0" can also be "C:", "D:" and "SCSI0:0,1,0". The two volume names
144 reflect that the disk has two partitions on it. Disk partitions that
145 are not recognized by Windows are not usually given a volume name. How‐
146 ever Vista does show a volume name for a disk which has no partitions
147 recognized by it and when selected invites the user to format it (which
148 may be rather unfriendly to other OSes).
149 These utilities assume a given device name is in the Win32 device
151 namespace. To make that explicit "\\.\" can be prepended to the device
152 names mentioned in this section. Beware that backslash is an escape
153 character in Unix like shells and the C programming language. In a
154 shell like Msys (from MinGW) each backslash may need to be typed twice.
155 The sg_scan utility within this package lists out Windows device names
157 in a form that is suitable for other utilities in this package to use.
158
160 SCSI disks have block names of the form /dev/da<num> where <num> is an
161 integer starting at zero. The "da" is replaced by "sa" for SCSI tape
162 drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a cor‐
163 responding pass-through device name of the form /dev/pass<num> where
164 <num> is an integer starting at zero. The "camcontrol devlist" command
165 may be useful for finding out which SCSI device names are available and
166 the correspondence between class and pass-through names.
167
169 SCSI device names below the /dev directory have a form like: c5t4d3s2
170 where the number following "c" is the controller (HBA) number, the num‐
171 ber following "t" is the target number (from the SCSI parallel inter‐
172 face days) and the number following "d" is the LUN. Following the "s"
173 is the slice number which is related to a partition and by convention
174 "s2" is the whole disk.
175 OpenSolaris also has a c5t4d3p2 form where the number following the "p"
177 is the partition number apart from "p0" which is the whole disk. So a
178 whole disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 .
179 And these device names are duplicated in the /dev/dsk and /dev/rdsk
181 directories. The former is the block device name and the latter is for
182 "raw" (or char device) access which is what sg3_utils needs. So in
183 OpenSolaris something of the form 'sg_inq /dev/rdsk/c5t4d3p0' should
184 work. If it doesn't work then add a '-vvv' option for more debug
185 information. Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk"
186 changed to "dsk") will result in an "inappropriate ioctl for device"
187 error.
188 The device names within the /dev directory are typically symbolic links
190 to much longer topological names in the /device directory. In Solaris
191 cd/dvd/bd drives seem to be treated as disks and so are found in the
192 /dev/rdsk directory. Tape drives appear in the /dev/rmt directory.
193 There is also a sgen (SCSI generic) driver which by default does not
195 attach to any device. See the /kernel/drv/sgen.conf file to control
196 what is attached. Any attached device will have a device name of the
197 form /dev/scsi/c5t4d3 .
198 Listing available SCSI devices in Solaris seems to be a challenge. "Use
200 the 'format' command" advice works but seems a very dangerous way to
201 list devices. [It does prompt again before doing any damage.] 'devfsadm
202 -Cv' cleans out the clutter in the /dev/rdsk directory, only leaving
203 what is "live". The "cfgadm -v" command looks promising.
204
206 To aid scripts that call these utilities, the exit status is set to
207 indicate success (0) or failure (1 or more). Note that some of the
208 lower values correspond to the SCSI sense key values. The exit status
209 values are:
210 0 success
212 1 syntax error. Either illegal command line options, options with
214 bad arguments or a combination of options that is not permitted.
215 2 the DEVICE reports that it is not ready for the operation
217 requested. The DEVICE may be in the process of becoming ready
218 (e.g. spinning up but not at speed) so the utility may work
219 after a wait. In Linux the DEVICE may be temporarily blocked
220 while error recovery is taking place.
221 3 the DEVICE reports a medium or hardware error (or a blank
223 check). For example an attempt to read a corrupted block on a
224 disk will yield this value.
225 5 the DEVICE reports an "illegal request" with an additional sense
227 code other than "invalid command operation code". This is often
228 a supported command with a field set requesting an unsupported
229 capability. For commands that require a "service action" field
230 this value can indicate that the command with that service
231 action value is not supported.
232 6 the DEVICE reports a "unit attention" condition. This usually
234 indicates that something unrelated to the requested command has
235 occurred (e.g. a device reset) potentially before the current
236 SCSI command was sent. The requested command has not been exe‐
237 cuted by the device. Note that unit attention conditions are
238 usually only reported once by a device.
239 7 the DEVICE reports a "data protect" sense key. This implies some
241 mechanism has blocked writes (or possibly all access to the
242 media).
243 9 the DEVICE reports an illegal request with an additional sense
245 code of "invalid command operation code" which means that it
246 doesn't support the requested command.
247 10 the DEVICE reports a "copy aborted". This implies another com‐
249 mand or device problem has stopped a copy operation. The
250 EXTENDED COPY family of commands (including WRITE USING TOKEN)
251 may return this sense key.
252 11 the DEVICE reports an aborted command. In some cases aborted
254 commands can be retried immediately (e.g. if the transport
255 aborted the command due to congestion).
256 14 the DEVICE reports a miscompare sense key. VERIFY and COMPARE
258 AND WRITE commands may report this.
259 15 the utility is unable to open, close or use the given DEVICE or
261 some other file. The given file name could be incorrect or there
262 may be permission problems. Adding the '-v' option may give more
263 information.
264 20 the DEVICE reports it has a check condition but "no sense" and
266 non-zero information in its additional sense codes. Some polling
267 commands (e.g. REQUEST SENSE) can receive this response. There
268 may be useful information in the sense data such as a progress
269 indication.
270 21 the DEVICE reports a "recovered error". The requested command
272 was successful. Most likely a utility will report a recovered
273 error to stderr and continue, probably leaving the utility with
274 an exit status of 0 .
275 24 the DEVICE reports a SCSI status of "reservation conflict". This
277 means access to the DEVICE with the current command has been
278 blocked because another machine (HBA or SCSI "initiator") holds
279 a reservation on this DEVICE. On modern SCSI systems this is
280 related to the use of the PERSISTENT RESERVATION family of com‐
281 mands.
282 25 the DEVICE reports a SCSI status of "condition met". Currently
284 only the PRE-FETCH command (see SBC-4) yields this status.
285 26 the DEVICE reports a SCSI status of "busy". SAM-5 defines this
287 status as the logical unit is temporarily unable to process a
288 command. It is recommended to re-issue the command.
289 27 the DEVICE reports a SCSI status of "task set full".
291 28 the DEVICE reports a SCSI status of "ACA active". ACA is "auto
293 contingent allegiance" and is seldom used.
294 29 the DEVICE reports a SCSI status of "task aborted". SAM-5 says:
296 "This status shall be returned if a command is aborted by a com‐
297 mand or task management function on another I_T nexus and the
298 Control mode page TAS bit is set to one".
299 33 the command sent to DEVICE has timed out.
301 40 the command sent to DEVICE has received an "aborted command"
303 sense key with an additional sense code of 0x10. This group is
304 related to problems with protection information (PI or DIF). For
305 example this error may occur when reading a block on a drive
306 that has never been written (or is unmapped) if that drive was
307 formatted with type 1, 2 or 3 protection.
308 97 a SCSI command response failed sanity checks.
310 98 the DEVICE reports it has a check condition but the error
312 doesn't fit into any of the above categories.
313 99 any errors that can't be categorized into values 1 to 98 may
315 yield this value. This includes transport and operating system
316 errors after the command has been sent to the device.
317 126 the utility was found but could not be executed. That might
319 occur if the executable does not have execute permissions.
320 127 This is the exit status for utility not found. That might occur
322 when a script calls a utility in this package but the PATH envi‐
323 ronment variable has not been properly set up, so the script
324 cannot find the executable.
325 128 + <signum>
327 If a signal kills a utility then the exit status is 128 plus the
328 signal number. For example if a segmentation fault occurs then a
329 utility is typically killed by SIGSEGV which according to 'man 7
330 signal' has an associated signal number of 11; so the exit sta‐
331 tus will be 139 .
332 255 the utility tried to yield an exit status of 255 or larger. That
334 should not happen; given here for completeness.
335 Most of the error conditions reported above will be repeatable (an
337 example of one that is not is "unit attention") so the utility can be
338 run again with the '-v' option (or several) to obtain more information.
339
341 Arguments to long options are mandatory for short options as well. In
342 the short form an argument to an option uses zero or more spaces as a
343 separator (i.e. the short form does not use "=" as a separator).
344 If an option takes a numeric argument then that argument is assumed to
346 be decimal unless otherwise indicated (e.g. with a leading "0x", a
347 trailing "h" or as noted in the usage message).
348 Some options are used uniformly in most of the utilities in this pack‐
350 age. Those options are listed below. Note that there are some excep‐
351 tions.
352 -e, --enumerate
354 some utilities (e.g. sg_ses and sg_vpd) store a lot of informa‐
355 tion in internal tables. This option will output that informa‐
356 tion in some readable form (e.g. sorted by an acronym or by page
357 number) then exit. Note that with this option DEVICE is ignored
358 (as are most other options) and no SCSI IO takes place, so the
359 invoker does not need any elevated permissions.
360 -h, -?, --help
362 output the usage message then exit. In a few older utilities the
363 '-h' option requests hexadecimal output. In these cases the '-?'
364 option will output the usage message then exit.
365 -H, --hex
367 for SCSI commands that yield a non-trivial response, print out
368 that response in ASCII hexadecimal. To produce hexadecimal that
369 can be parsed by other utilities (e.g. without a relative
370 address to the left and without trailing ASCII) use this option
371 three or four times.
372 -i, --in=FN
374 many SCSI commands fetch a significant amount of data (returned
375 in the data-in buffer) which several of these utilities decode
376 (e.g. sg_vpd and sg_logs). To separate the two steps of fetching
377 the data from a SCSI device and then decoding it, this option
378 has been added. The first step (fetching the data) can be done
379 using the --hex or --raw option and redirecting the command line
380 output to a file (often done with ">" in Unix based operating
381 systems). The difference between --hex and --raw is that the
382 former produces output in ASCII hexadecimal while --raw produces
383 its output in "raw" binary.
384 The second step (i.e. decoding the SCSI response data now held
385 in a file) can be done using this --in=FN option where the file
386 name is FN. If "-" is used for FN then stdin is assumed, again
387 this allows for command line redirection (or piping). That file
388 (or stdin) is assumed to contain ASCII hexadecimal unless the
389 --raw option is also given in which case it is assumed to be
390 binary. Notice that the meaning of the --raw option is "flipped"
391 when used with --in=FN to act on the input, typically it acts on
392 the output data.
393 Since the structure of the data returned by SCSI commands varies
394 considerably then the usage information or manpage of the util‐
395 ity being used should be checked. In some cases --hex may need
396 to be used multiple times (and is more conveniently given as
397 '-HH' or '-HHH). In other cases the name of this option is
398 --inhex=FN.
399 -m, --maxlen=LEN
401 several important SCSI commands (e.g. INQUIRY and MODE SENSE)
402 have response lengths that vary depending on many factors, only
403 some of which these utilities take into account. The maximum
404 response length is typically specified in the 'allocation
405 length' field of the cdb. In the absence of this option, several
406 utilities use a default allocation length (sometimes recommended
407 in the SCSI draft standards) or a "double fetch" strategy. See
408 sg_logs(8) for its description of a "double fetch" strategy.
409 These techniques are imperfect and in the presence of faulty
410 SCSI targets can cause problems (e.g. some USB mass storage
411 devices freeze if they receive an INQUIRY allocation length
412 other than 36). Also use of this option disables any "double
413 fetch" strategy that may have otherwise been used.
414 -r, --raw
416 for SCSI commands that yield a non-trivial response, output that
417 response in binary to stdout. If any error messages or warning
418 are produced they are usually sent to stderr so as to not inter‐
419 fere with the output from this option.
420 Some utilities that consume data to send to the DEVICE along
421 with the SCSI command, use this option. Alernatively the --in=FN
422 option causes DEVICE to be ignored and the response data (to be
423 decoded) fetched from a file named FN. In these cases this
424 option may indicate that binary data can be read from stdin or
425 from a nominated file (e.g. FN).
426 -v, --verbose
428 increase the level of verbosity, (i.e. debug output). Can be
429 used multiple times to further increase verbosity. The addi‐
430 tional output is usually sent to stderr.
431 -V, --version
433 print the version string and then exit. Each utility has its own
434 version number and date of last code change.
435
437 Many utilities have command line options that take numeric arguments.
438 These numeric arguments can be large values (e.g. a logical block
439 address (LBA) on a disk) and can be inconvenient to enter in the
440 default decimal representation. So various other representations are
441 permitted.
442 Multiplicative suffixes are accepted. They are one, two or three letter
444 strings appended directly after the number to which they apply:
445 c C *1
447 w W *2
448 b B *512
449 k K KiB *1024
450 KB *1000
451 m M MiB *1048576
452 MB *1000000
453 g G GiB *(2^30)
454 GB *(10^9)
455 t T TiB *(2^40)
456 TB *(10^12)
457 p P PiB *(2^50)
458 PB *(10^15)
459 An example is "2k" for 2048. The large tera and peta suffixes are only
461 available for numeric arguments that might require 64 bits to represent
462 internally.
463 A suffix of the form "x<n>" multiplies the leading number by <n>. An
465 example is "2x33" for "66". The leading number cannot be "0" (zero) as
466 that would be interpreted as a hexadecimal number (see below).
467 These multiplicative suffixes are compatible with GNU's dd command
469 (since 2002) which claims compliance with SI and with IEC 60027-2.
470 Alternatively numerical arguments can be given in hexadecimal. There
472 are two syntaxes. The number can be preceded by either "0x" or "0X" as
473 found in the C programming language. The second hexadecimal representa‐
474 tion is a trailing "h" or "H" as found in (storage) standards. When hex
475 numbers are given, multipliers cannot be used. For example the decimal
476 value "256" can be given as "0x100" or "100h".
477
479 There are two standardized methods for downloading microcode (i.e.
480 device firmware) to a SCSI device. The more general way is with the
481 SCSI WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclo‐
482 sures have their own method based on the Download microcode con‐
483 trol/status diagnostic page, see the sg_ses_microcode utility.
484
486 There are several bash shell scripts in the 'scripts' subdirectory that
487 invoke compiled utilities (e.g. sg_readcap). Several of the scripts
488 start with 'scsi_' rather than 'sg_'. One purpose of these scripts is
489 to call the same utility (e.g. sg_readcap) on multiple devices. Most of
490 the basic compiled utilities only allow one device as an argument. Some
491 distributions install these scripts in a more visible directory (e.g.
492 /usr/bin). Some of these scripts have man page entries. See the README
493 file in the 'scripts' subdirectory.
494 There is some example C code plus examples of complex invocations in
496 the 'examples' subdirectory. There is also a README file. The example C
497 may be a simpler example of how to use a SCSI pass-through in Linux
498 than the main utilities (found in the 'src' subdirectory). This is due
499 to the fewer abstraction layers (e.g. they don't worry the MinGW in
500 Windows may open a file in text rather than binary mode).
501 Some utilities that the author has found useful have been placed in the
503 'utils' subdirectory.
504
506 There is a web page discussing this package at
507 http://sg.danny.cz/sg/sg3_utils.html . The device naming used by this
508 package on various operating systems is discussed at:
509 http://sg.danny.cz/sg/device_name.html .
510
512 Written by Douglas Gilbert. Some utilities have been contributed, see
513 the CREDITS file and individual source files (in the 'src' directory).
514
516 Report bugs to <dgilbert at interlog dot com>.
517
519 Copyright © 1999-2016 Douglas Gilbert
520 Some utilities are distributed under a GPL version 2 license while oth‐
521 ers, usually more recent ones, are under a FreeBSD license. The files
522 that are common to almost all utilities and thus contain the most reus‐
523 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and
524 sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty;
525 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
526
528 sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
529sg3_utils-1.42 February 2016 SG3_UTILS(8)