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/HD_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 To aid scripts that call these utilities, the exit status is set to
81 indicate success (0) or failure (1 or more). Note that some of the
82 lower values correspond to the SCSI sense key values. The exit status
83 values are:
84 0 success
86 1 syntax error. Either illegal command line options, options with
88 bad arguments or a combination of options that is not permitted.
89 2 the DEVICE reports that it is not ready for the operation
91 requested. The device may be in the process of becoming ready
92 (e.g. spinning up but not at speed) so the utility may work
93 after a wait.
94 3 the DEVICE reports a medium or hardware error (or a blank
96 check). For example an attempt to read a corrupted block on a
97 disk will yield this value.
98 5 the DEVICE reports an "illegal request" with an additional sense
100 code other than "invalid command operation code". This is often
101 a supported command with a field set requesting an unsupported
102 capability. For commands that require a "service action" field
103 this value can indicate that the command with that service
104 action value is not supported.
105 6 the DEVICE reports a "unit attention" condition. This usually
107 indicates that something unrelated to the requested command has
108 occurred (e.g. a device reset) potentially before the current
109 SCSI command was sent. The requested command has not been exe‐
110 cuted by the device. Note that unit attention conditions are
111 usually only reported once by a device.
112 9 the DEVICE reports an illegal request with an additional sense
114 code of "invalid command operation code" which means that it
115 doesn't support the requested command.
116 11 the DEVICE reports an aborted command. In some cases aborted
118 commands can be retried immediately (e.g. if the transport
119 aborted the command due to congestion).
120 15 the utility is unable to open, close or use the given DEVICE.
122 The given file name could be incorrect or there may be permis‐
123 sion problems. Adding the '-v' option may give more information.
124 20 the DEVICE reports it has a check condition but "no sense" and
126 non-zero information in its additional sense codes. Some polling
127 commands (e.g. REQUEST SENSE) can receive this response.
128 21 the DEVICE reports a "recovered error". The requested command
130 was successful. Most likely a utility will report a recovered
131 error to stderr and continue, probably leaving the utility with
132 an exit status of 0 .
133 33 the command sent to DEVICE has timed out.
135 97 the response to a SCSI command failed sanity checks.
137 98 the DEVICE reports it has a check condition but the error
139 doesn't fit into any of the above categories.
140 99 any errors that can't be categorized into values 1 to 98 may
142 yield this value. This includes transport and operating system
143 errors after the command has been sent to the device.
144 Most of the error conditions reported above will be repeatable (an
146 example of one that is not is "unit attention") so the utility can be
147 run again with the '-v' option (or several) to obtain more information.
148
150 Arguments to long options are mandatory for short options as well. In
151 the short form an argument to an option uses zero or more spaces as a
152 separator (i.e. the short form does not use "=" as a separator).
153 If an option takes a numeric argument then that argument is assumed to
155 be decimal unless otherwise indicated (e.g. with a leading "0x", a
156 trailing "h" or as noted in the usage message).
157 -h, -?, --help
159 output the usage message then exit. In a few older utilities the
160 '-h' option requests hexadecimal output. In these cases the '-?'
161 option will output the usage message then exit.
162 -H, --hex
164 for SCSI commands that yield a non-trivial response, print out
165 that response in ASCII hexadecimal.
166 -m, --maxlen=LEN
168 several important SCSI commands (e.g. INQUIRY and MODE SENSE)
169 have response lengths that vary depending on many factors, only
170 some of which these utilities take into account. The maximum
171 response length is typically specified in the 'allocation
172 length' field of the cdb. In the absence of this option, several
173 utilities use a default allocation length (sometimes recommended
174 in the SCSI draft standards) or a "double fetch" strategy. See
175 sg_logs(8) for its description of a "double fetch" strategy.
176 These techniques are imperfect and in the presence of faulty
177 SCSI targets can cause problems (e.g. some USB mass storage
178 devices freeze if they receive an INQUIRY allocation length
179 other than 36). Also use of this option disables any "double
180 fetch" strategy that may have otherwise been used.
181 -r, --raw
183 for SCSI commands that yield a non-trivial response, output that
184 response in binary to stdout. If any error messages or warning
185 are produced they are usually sent to stderr. Some utilities
186 that consume data to send to the device along with the SCSI com‐
187 mand, use this option to provide that data or indicate that it
188 can be read from stdin.
189 -v, --verbose
191 increase the level of verbosity, (i.e. debug output). Can be
192 used multiple times to further increase verbosity. The addi‐
193 tional output is usually sent to stderr.
194 -V, --version
196 print the version string and then exit. Each utility has its own
197 version number and date of last code change.
198
200 Many utilities have command line options that take numeric arguments.
201 These numeric arguments can be large values (e.g. a logical block
202 address (LBA) on a disk) and can be inconvenient to enter in the
203 default decimal representation. So various other representations are
204 permitted.
205 Multiplicative suffixes are accepted. They are one, two or three letter
207 strings appended directly after the number to which they apply:
208 c C *1
210 w W *2
211 b B *512
212 k K KiB *1024
213 KB *1000
214 m M MiB *1048576
215 MB *1000000
216 g G GiB *(2^30)
217 GB *(10^9)
218 t T TiB *(2^40)
219 TB *(10^12)
220 p P PiB *(2^50)
221 PB *(10^15)
222 An example is "2k" for 2048. The large tera and peta suffixes are only
224 available for numeric arguments that might require 64 bits to represent
225 internally.
226 A suffix of the form "x<n>" multiplies the leading number by <n>. An
228 example is "2x33" for "66". The leading number cannot be "0" (zero) as
229 that would be interpreted as a hexadecimal number (see below).
230 These multiplicative suffixes are compatible with GNU's dd command
232 (since 2002) which claims compliance with SI and with IEC 60027-2.
233 Alternatively numerical arguments can be given in hexadecimal. There
235 are two syntaxes. The number can be preceded by either "0x" or "0X" as
236 found in the C programming language. The second hexadecimal representa‐
237 tion is a trailing "h" or "H" as found in (storage) standards. When hex
238 numbers are given, multipliers cannot be used. For example the decimal
239 value "256" can be given as "0x100" or "100h".
240
242 There are several bourne shell scripts in the 'scripts' subdirectory
243 that invoke compiled utilities (e.g. sg_readcap). The scripts start
244 with 'scsi_' rather than 'sg_'. One purpose of these scripts is to call
245 the same utility (e.g. sg_readcap) on multiple disks. Most of the basic
246 compiled utilities only allow one device as an argument. Some distribu‐
247 tions install these scripts in a visible directory (e.g. /usr/src/bin).
248 Some of these scripts have man page entries. See the README file in the
249 'scripts' subdirectory.
250 There is some example C code plus examples of complex invocations in
252 the 'examples' subdirectory. There is also a README file. The example C
253 may be a simpler example of how to use a SCSI pass-through in Linux
254 than the main utilities (found in the 'src' subdirectory). This is due
255 to the fewer abstraction layers (e.g. they don't worry the MinGW in
256 Windows may open a file in text rather than binary mode).
257 Some utilities that the author has found useful have been placed in the
259 'utils' subdirectory.
260
262 There is a web page discussing this package at
263 http://sg.danny.cz/sg/sg3_utils.html .
264
266 Written by Douglas Gilbert. Some utilities have been contributed, see
267 the CREDITS file and individual source files (in the 'src' directory).
268
270 Report bugs to <dgilbert at interlog dot com>.
271
273 Copyright © 1999-2010 Douglas Gilbert
274 Some utilities are distributed under a GPL version 2 license while oth‐
275 ers, usually more recent ones, are under a FreeBSD license. The files
276 that are common to almost all utilities and thus contain the most reus‐
277 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and
278 sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty;
279 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
280
282 sdparm(sdparm), ddpt(ddpt), mt(1)
283sg3_utils-1.29 February 2010 SG3_UTILS(8)