1SG3_UTILS(8) SG3_UTILS SG3_UTILS(8)
2
6 sg3_utils - a package of utilities for sending SCSI commands
7
9 sg_* [--help] [--hex] [--maxlen=LEN] [--raw] [--verbose] [--version]
10 [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.
22 SCSI draft standards can be found at http://www.t10.org . The standards
24 themselves can be purchased from ANSI and other standards organiza‐
25 tions. A good overview of various SCSI standards can be seen in
26 http://www.t10.org/scsi-3.htm with the SCSI command sets in the upper
27 part of the diagram. SCSI commands in common with all device types can
28 be found in SPC of which SPC-4 is the latest major version. Block
29 device specific commands (e.g. as used by disks) are in SBC, those for
30 tape drives in SSC and those for CD/DVD/BD drives in MMC.
31 It is becoming more common to control ATA disks with the SCSI command
33 set. This involves the translation of SCSI commands to their corre‐
34 sponding ATA equivalents (and that is an imperfect mapping in some
35 cases). The relevant standard is called SCSI to ATA Translation (SAT
36 and SAT-2 are now standards at INCITS(ANSI) and ISO while SAT-3 is at
37 the draft stage). The logic to perform the command translation is often
38 called a SAT Layer or SATL and may be within an operating system, in
39 host bus adapter firmware or in an external device (e.g. associated
40 with a SAS expander). See http://www.t10.org for more information.
41 There is some support for SCSI tape devices but not for their basic
43 commands. The reader is referred to the "mt" utility.
44 There are two generations of command line option usage. The newer util‐
46 ities (written since July 2004) use the getopt_long() function to parse
47 command line options. With that function, each option has two represen‐
48 tations: a short form (e.g. '-v') and a longer form (e.g. '--verbose').
49 If an argument is required then it follows a space (optionally) in the
50 short form and a "=" in the longer form (e.g. in the sg_verify utility
51 '-l 2a6h' and '--lba=2a6h' are equivalent). Note that with
52 getopt_long(), short form options can be elided, for example: '-all' is
53 equivalent to '-a -l -l'. The DEVICE argument may appear after,
54 between or prior to any options.
55 The older utilities, such as sg_inq, had individual command line pro‐
57 cessing code typically based on a single "-" followed by one or more
58 characters. If an argument is needed then it follows a "=" (e.g.
59 '-p=1f' in sg_modes with its older interface). Various options can be
60 elided as long as it is not ambiguous (e.g. '-vv' to increase the ver‐
61 bosity).
62 Over time the command line interface of these older utilities became
64 messy and overloaded with options. So in sg3_utils version 1.23 the
65 command line interface of these older utilities was altered to have
66 both a cleaner getopt_long() interface and their older interface for
67 backward compatibility. By default these older utilities use their
68 getopt_long() based interface. That can be overridden by defining the
69 SG3_UTILS_OLD_OPTS environment variable or using '-O' or '--old' as the
70 first command line option. The man pages of the older utilities docu‐
71 ments the details.
72 Several sg3_utils utilities are based on the Unix dd command (e.g.
74 sg_dd) and permit copying data at the level of SCSI READ and WRITE com‐
75 mands. sg_dd is tightly bound to Linux and hence is not ported to other
76 OSes. A more generic utility (than sg_dd) called ddpt in a package of
77 the same name has been ported to other OSes.
78
80 Normal disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc,
81 etc. SCSI disks in Linux have always had names like that but in recent
82 Linux kernels (e.g. lk 2.6 series) it is becoming more common for
83 almost all disks to be named like that. Partitions within a disk are
84 specified by a number appended to the device name, starting at 1 (e.g.
85 /dev/sda1 ).
86 Tape drives are named /dev/st<num> or /dev/nst<num> where <num> starts
88 at zero. Additionally one letter from this list: "lma" may be appended
89 to the name. CD, DVD and BD readers (and writers) are named
90 /dev/sr<num> where <num> start at zero. There are less used SCSI device
91 type names, the dmesg and the lsscsi commands may help to find if any
92 are attached to a running system.
93 There is also a SCSI device driver which offers alternate generic
95 access to SCSI devices. It uses names of the form /dev/sg<num> where
96 <num> starts at zero. The "lsscsi -g" command may be useful in finding
97 these and which generic name corresponds to a device type name (e.g.
98 /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI
99 generic driver was introduced and its names are of the form
100 /dev/bsg/<h:c:t:l> where h, c, t and l are numbers. Again see the lss‐
101 csi command to find the correspondence between that SCSI tuple (i.e.
102 <h:c:t:l>) and alternate device names.
103 Prior to the Linux kernel 2.6 series these utilities could only use
105 generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux
106 kernel 2.6 series, any device name can be used by these utilities.
107
109 Storage and related devices can have several device names in Windows.
110 Probably the most common in the volume name (e.g. "D:"). There are also
111 a "class" device names such as "PhysicalDrive<n>", "CDROM<n>" and
112 "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order
113 as devices are discovered (and sometimes rediscovered).
114 Some storage devices have a SCSI lower level device name which starts
116 with a SCSI (pseudo) adapter name of the form "SCSI<n>:". To this is
117 added sub-addressing in the form of a "bus" number, a "target" identi‐
118 fier and a LUN (Logical Unit Number). The "bus" number is also known as
119 a "PathId". These are assembled to form a device name of the form:
120 "SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted in
121 which case a LUN of zero is assumed. This lower level device name can‐
122 not often be used directly since Windows blocks attempts to use it if a
123 class driver has "claimed" the device. There are SCSI device types
124 (e.g. Automation/Drive interface type) for which there is no class
125 driver. At least two transports ("bus types" in Windows jargon): USB
126 and IEEE 1394 do not have a "scsi" device names of this form.
127 In keeping with DOS file system conventions, the various device names
129 can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
130 tedious to write, a shortened form of "PD<n>" is permitted by all util‐
131 ities in this package.
132 A single device (e.g. a disk) can have many device names. For example:
134 "PD0" can also be "C:", "D:" and "SCSI0:0,1,0". The two volume names
135 reflect that the disk has two partitions on it. Disk partitions that
136 are not recognized by Windows are not usually given a volume name. How‐
137 ever Vista does show a volume name for a disk which has no partitions
138 recognized by it and when selected invites the user to format it (which
139 may be rather unfriendly to other OSes).
140 These utilities assume a given device name is in the Win32 device
142 namespace. To make that explicit "\\.\" can be prepended to the device
143 names mentioned in this section. Beware that backslash is an escape
144 character in Unix like shells and the C programming language. In a
145 shell like Msys (from MinGW) each backslash may need to be typed twice.
146 The sg_scan utility within this package lists out Windows device names
148 in a form that is suitable for other utilities in this package to use.
149
151 SCSI disks have block names of the form /dev/da<num> where <num> is an
152 integer starting at zero. The "da" is replaced by "sa" for SCSI tape
153 drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a cor‐
154 responding pass-through device name of the form /dev/pass<num> where
155 <num> is an integer starting at zero. The "camcontrol devlist" command
156 may be useful for finding out which SCSI device names are available and
157 the correspondence between class and pass-through names.
158
160 SCSI device names below the /dev directory have a form like: c5t4d3s2
161 where the number following "c" is the controller (HBA) number, the num‐
162 ber following "t" is the target number (from the SCSI parallel inter‐
163 face days) and the number following "d" is the LUN. Following the "s"
164 is the slice number which is related to a partition and by convention
165 "s2" is the whole disk.
166 OpenSolaris also has a c5t4d3p2 form where the number following the "p"
168 is the partition number apart from "p0" which is the whole disk. So a
169 whole disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 .
170 And these device names are duplicated in the /dev/dsk and /dev/rdsk
172 directories. The former is the block device name and the latter is for
173 "raw" (or char device) access which is what sg3_utils needs. So in
174 OpenSolaris something of the form 'sg_inq /dev/rdsk/c5t4d3p0' should
175 work. If it doesn't work then add a '-vvv' option for more debug
176 information. Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk"
177 changed to "dsk") will result in an "inappropriate ioctl for device"
178 error.
179 The device names within the /dev directory are typically symbolic links
181 to much longer topological names in the /device directory. In Solaris
182 cd/dvd/bd drives seem to be treated as disks and so are found in the
183 /dev/rdsk directory. Tape drives appear in the /dev/rmt directory.
184 There is also a sgen (SCSI generic) driver which by default does not
186 attach to any device. See the /kernel/drv/sgen.conf file to control
187 what is attached. Any attached device will have a device name of the
188 form /dev/scsi/c5t4d3 .
189 Listing available SCSI devices in Solaris seems to be a challenge. "Use
191 the 'format' command" advice works but seems a very dangerous way to
192 list devices. [It does prompt again before doing any damage.] 'devfsadm
193 -Cv' cleans out the clutter in the /dev/rdsk directory, only leaving
194 what is "live". The "cfgadm -v" command looks promising.
195
197 To aid scripts that call these utilities, the exit status is set to
198 indicate success (0) or failure (1 or more). Note that some of the
199 lower values correspond to the SCSI sense key values. The exit status
200 values are:
201 0 success
203 1 syntax error. Either illegal command line options, options with
205 bad arguments or a combination of options that is not permitted.
206 2 the DEVICE reports that it is not ready for the operation
208 requested. The device may be in the process of becoming ready
209 (e.g. spinning up but not at speed) so the utility may work
210 after a wait.
211 3 the DEVICE reports a medium or hardware error (or a blank
213 check). For example an attempt to read a corrupted block on a
214 disk will yield this value.
215 5 the DEVICE reports an "illegal request" with an additional sense
217 code other than "invalid command operation code". This is often
218 a supported command with a field set requesting an unsupported
219 capability. For commands that require a "service action" field
220 this value can indicate that the command with that service
221 action value is not supported.
222 6 the DEVICE reports a "unit attention" condition. This usually
224 indicates that something unrelated to the requested command has
225 occurred (e.g. a device reset) potentially before the current
226 SCSI command was sent. The requested command has not been exe‐
227 cuted by the device. Note that unit attention conditions are
228 usually only reported once by a device.
229 9 the DEVICE reports an illegal request with an additional sense
231 code of "invalid command operation code" which means that it
232 doesn't support the requested command.
233 11 the DEVICE reports an aborted command. In some cases aborted
235 commands can be retried immediately (e.g. if the transport
236 aborted the command due to congestion).
237 14 the DEVICE reports a miscompare sense key. VERIFY and COMPARE
239 AND WRITE commands may report this.
240 15 the utility is unable to open, close or use the given DEVICE.
242 The given file name could be incorrect or there may be permis‐
243 sion problems. Adding the '-v' option may give more information.
244 20 the DEVICE reports it has a check condition but "no sense" and
246 non-zero information in its additional sense codes. Some polling
247 commands (e.g. REQUEST SENSE) can receive this response.
248 21 the DEVICE reports a "recovered error". The requested command
250 was successful. Most likely a utility will report a recovered
251 error to stderr and continue, probably leaving the utility with
252 an exit status of 0 .
253 33 the command sent to DEVICE has timed out.
255 97 a SCSI command response failed sanity checks.
257 98 the DEVICE reports it has a check condition but the error
259 doesn't fit into any of the above categories.
260 99 any errors that can't be categorized into values 1 to 98 may
262 yield this value. This includes transport and operating system
263 errors after the command has been sent to the device.
264 126 the utility was found but could not be executed. That might
266 occur if the executable does not have execute permissions.
267 127 This is the exit status for utility not found. That might occur
269 when a script calls a utility in this package but the PATH envi‐
270 ronment variable has not been properly set up, so the script
271 cannot find the executable.
272 128 + <signum>
274 If a signal kills a utility then the exit status is 128 plus the
275 signal number. For example if a segmentation fault occurs then a
276 utility is typically killed by SIGSEGV which according to 'man 7
277 signal' has an associated signal number of 11; so the exit sta‐
278 tus will be 139 .
279 255 the utility tried to yield an exit status of 255 or larger. That
281 should not happen; given here for completeness.
282 Most of the error conditions reported above will be repeatable (an
284 example of one that is not is "unit attention") so the utility can be
285 run again with the '-v' option (or several) to obtain more information.
286
288 Arguments to long options are mandatory for short options as well. In
289 the short form an argument to an option uses zero or more spaces as a
290 separator (i.e. the short form does not use "=" as a separator).
291 If an option takes a numeric argument then that argument is assumed to
293 be decimal unless otherwise indicated (e.g. with a leading "0x", a
294 trailing "h" or as noted in the usage message).
295 Some options are used uniformly in most of the utilities in this pack‐
297 age. Those options are listed below. Note that there are some excep‐
298 tions.
299 -h, -?, --help
301 output the usage message then exit. In a few older utilities the
302 '-h' option requests hexadecimal output. In these cases the '-?'
303 option will output the usage message then exit.
304 -H, --hex
306 for SCSI commands that yield a non-trivial response, print out
307 that response in ASCII hexadecimal.
308 -m, --maxlen=LEN
310 several important SCSI commands (e.g. INQUIRY and MODE SENSE)
311 have response lengths that vary depending on many factors, only
312 some of which these utilities take into account. The maximum
313 response length is typically specified in the 'allocation
314 length' field of the cdb. In the absence of this option, several
315 utilities use a default allocation length (sometimes recommended
316 in the SCSI draft standards) or a "double fetch" strategy. See
317 sg_logs(8) for its description of a "double fetch" strategy.
318 These techniques are imperfect and in the presence of faulty
319 SCSI targets can cause problems (e.g. some USB mass storage
320 devices freeze if they receive an INQUIRY allocation length
321 other than 36). Also use of this option disables any "double
322 fetch" strategy that may have otherwise been used.
323 -r, --raw
325 for SCSI commands that yield a non-trivial response, output that
326 response in binary to stdout. If any error messages or warning
327 are produced they are usually sent to stderr. Some utilities
328 that consume data to send to the device along with the SCSI com‐
329 mand, use this option to provide that data or indicate that it
330 can be read from stdin.
331 -v, --verbose
333 increase the level of verbosity, (i.e. debug output). Can be
334 used multiple times to further increase verbosity. The addi‐
335 tional output is usually sent to stderr.
336 -V, --version
338 print the version string and then exit. Each utility has its own
339 version number and date of last code change.
340
342 Many utilities have command line options that take numeric arguments.
343 These numeric arguments can be large values (e.g. a logical block
344 address (LBA) on a disk) and can be inconvenient to enter in the
345 default decimal representation. So various other representations are
346 permitted.
347 Multiplicative suffixes are accepted. They are one, two or three letter
349 strings appended directly after the number to which they apply:
350 c C *1
352 w W *2
353 b B *512
354 k K KiB *1024
355 KB *1000
356 m M MiB *1048576
357 MB *1000000
358 g G GiB *(2^30)
359 GB *(10^9)
360 t T TiB *(2^40)
361 TB *(10^12)
362 p P PiB *(2^50)
363 PB *(10^15)
364 An example is "2k" for 2048. The large tera and peta suffixes are only
366 available for numeric arguments that might require 64 bits to represent
367 internally.
368 A suffix of the form "x<n>" multiplies the leading number by <n>. An
370 example is "2x33" for "66". The leading number cannot be "0" (zero) as
371 that would be interpreted as a hexadecimal number (see below).
372 These multiplicative suffixes are compatible with GNU's dd command
374 (since 2002) which claims compliance with SI and with IEC 60027-2.
375 Alternatively numerical arguments can be given in hexadecimal. There
377 are two syntaxes. The number can be preceded by either "0x" or "0X" as
378 found in the C programming language. The second hexadecimal representa‐
379 tion is a trailing "h" or "H" as found in (storage) standards. When hex
380 numbers are given, multipliers cannot be used. For example the decimal
381 value "256" can be given as "0x100" or "100h".
382
384 There are several bash shell scripts in the 'scripts' subdirectory that
385 invoke compiled utilities (e.g. sg_readcap). The scripts start with
386 'scsi_' rather than 'sg_'. One purpose of these scripts is to call the
387 same utility (e.g. sg_readcap) on multiple disks. Most of the basic
388 compiled utilities only allow one device as an argument. Some distribu‐
389 tions install these scripts in a visible directory (e.g. /usr/src/bin).
390 Some of these scripts have man page entries. See the README file in the
391 'scripts' subdirectory.
392 There is some example C code plus examples of complex invocations in
394 the 'examples' subdirectory. There is also a README file. The example C
395 may be a simpler example of how to use a SCSI pass-through in Linux
396 than the main utilities (found in the 'src' subdirectory). This is due
397 to the fewer abstraction layers (e.g. they don't worry the MinGW in
398 Windows may open a file in text rather than binary mode).
399 Some utilities that the author has found useful have been placed in the
401 'utils' subdirectory.
402
404 There is a web page discussing this package at
405 http://sg.danny.cz/sg/sg3_utils.html . The device naming used by this
406 package on various operating systems is discussed at:
407 http://sg.danny.cz/sg/device_name.html .
408
410 Written by Douglas Gilbert. Some utilities have been contributed, see
411 the CREDITS file and individual source files (in the 'src' directory).
412
414 Report bugs to <dgilbert at interlog dot com>.
415
417 Copyright © 1999-2013 Douglas Gilbert
418 Some utilities are distributed under a GPL version 2 license while oth‐
419 ers, usually more recent ones, are under a FreeBSD license. The files
420 that are common to almost all utilities and thus contain the most reus‐
421 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and
422 sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty;
423 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
424
426 sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
427sg3_utils-1.37 October 2013 SG3_UTILS(8)