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 There are two generations of command line option usage. The newer util‐
33 ities (written since July 2004) use the getopt_long() function to parse
34 command line options. With that function, each option has two represen‐
35 tations: a short form (e.g. '-v') and a longer form (e.g. '--verbose').
36 If an argument is required then it follows a space (optionally) in the
37 short form and a "=" in the longer form (e.g. in the sg_verify utility
38 '-l 2a6h' and '--lba=2a6h' are equivalent). Note that with
39 getopt_long(), short form options can be elided, for example: '-all' is
40 equivalent to '-a -l -l'. The DEVICE argument may appear after,
41 between or prior to any options.
42 The older utilities, such as sg_inq, had individual command line pro‐
44 cessing code typically based on a single "-" followed by one or more
45 characters. If an argument is needed then it follows a "=" (e.g.
46 '-p=1f' in sg_modes with its older interface). Various options can be
47 elided as long as it is not ambiguous (e.g. '-vv' to increase the ver‐
48 bosity).
49 Over time the command line interface of these older utilities became
51 messy and overloaded with options. So in sg3_utils version 1.23 the
52 command line interface of these older utilities was altered to have
53 both a cleaner getopt_long() interface and their older interface for
54 backward compatibility. By default these older utilities use their
55 getopt_long() based interface. That can be overridden by defining the
56 SG3_UTILS_OLD_OPTS environment variable or using '-O' or '--old' as the
57 first command line option. The man pages of the older utilities docu‐
58 ments the details.
59 Several sg3_utils utilities are based on the Unix dd command (e.g.
61 sg_dd) and permit copying data at the level of SCSI READ and WRITE com‐
62 mands. sg_dd is tightly bound to Linux and hence is not ported to other
63 OSes. A more generic utility (than sg_dd) called ddpt in a package of
64 the same name has been ported to other OSes.
65
67 To aid scripts that call these utilities, the exit status is set to
68 indicate success (0) or failure (1 or more). Note that some of the
69 lower values correspond to the SCSI sense key values. The exit status
70 values are:
71 0 success
73 1 syntax error. Either illegal command line options, options with
75 bad arguments or a combination of options that is not permitted.
76 2 the DEVICE reports that it is not ready for the operation
78 requested. The device may be in the process of becoming ready
79 (e.g. spinning up but not at speed) so the utility may work
80 after a wait.
81 3 the DEVICE reports a medium or hardware error (or a blank
83 check). For example an attempt to read a corrupted block on a
84 disk will yield this value.
85 5 the DEVICE reports an "illegal request" with an additional sense
87 code other than "invalid command operation code". This is often
88 a supported command with a field set requesting an unsupported
89 capability. For commands that require a "service action" field
90 this value can indicate that the command with that service
91 action value is not supported.
92 6 the DEVICE reports a "unit attention" condition. This usually
94 indicates that something unrelated to the requested command has
95 occurred (e.g. a device reset) potentially before the current
96 SCSI command was sent. The requested command has not been exe‐
97 cuted by the device. Note that unit attention conditions are
98 usually only reported once by a device.
99 9 the DEVICE reports an illegal request with an additional sense
101 code of "invalid command operation code" which means that it
102 doesn't support the requested command.
103 11 the DEVICE reports an aborted command. In some cases aborted
105 commands can be retried immediately (e.g. if the transport
106 aborted the command due to congestion).
107 15 the utility is unable to open, close or use the given DEVICE.
109 The given file name could be incorrect or there may be permis‐
110 sion problems. Adding the '-v' option may give more information.
111 20 the DEVICE reports it has a check condition but "no sense" and
113 non-zero information in its additional sense codes. Some polling
114 commands (e.g. REQUEST SENSE) can receive this response.
115 21 the DEVICE reports a "recovered error". The requested command
117 was successful. Most likely a utility will report a recovered
118 error to stderr and continue, probably leaving the utility with
119 an exit status of 0 .
120 33 the command sent to DEVICE has timed out.
122 97 the response to a SCSI command failed sanity checks.
124 98 the DEVICE reports it has a check condition but the error
126 doesn't fit into any of the above categories.
127 99 any errors that can't be categorized into values 1 to 98 may
129 yield this value. This includes transport and operating system
130 errors after the command has been sent to the device.
131 Most of the error conditions reported above will be repeatable (an
133 example of one that is not is "unit attention") so the utility can be
134 run again with the '-v' option (or several) to obtain more information.
135
137 Arguments to long options are mandatory for short options as well. In
138 the short form an argument to an option uses zero or more spaces as a
139 separator (i.e. the short form does not use "=" as a separator).
140 If an option takes a numeric argument then that argument is assumed to
142 be decimal unless otherwise indicated (e.g. with a leading "0x", a
143 trailing "h" or as noted in the usage message).
144 -h, -?, --help
146 output the usage message then exit. In a few older utilities the
147 '-h' option requests hexadecimal output. In these cases the '-?'
148 option will output the usage message then exit.
149 -H, --hex
151 for SCSI commands that yield a non-trivial response, print out
152 that response in ASCII hexadecimal.
153 -m, --maxlen=LEN
155 several important SCSI commands (e.g. INQUIRY and MODE SENSE)
156 have response lengths that vary depending on many factors, only
157 some of which these utilities take into account. The maximum
158 response length is typically specified in the 'allocation
159 length' field of the cdb. In the absence of this option, several
160 utilities use a default allocation length (sometimes recommended
161 in the SCSI draft standards) or a "double fetch" strategy. See
162 sg_logs(8) for its description of a "double fetch" strategy.
163 These techniques are imperfect and in the presence of faulty
164 SCSI targets can cause problems (e.g. some USB mass storage
165 devices freeze if they receive an INQUIRY allocation length
166 other than 36). Also use of this option disables any "double
167 fetch" strategy that may have otherwise been used.
168 -r, --raw
170 for SCSI commands that yield a non-trivial response, output that
171 response in binary to stdout. If any error messages or warning
172 are produced they are usually sent to stderr. Some utilities
173 that consume data to send to the device along with the SCSI com‐
174 mand, use this option to provide that data or indicate that it
175 can be read from stdin.
176 -v, --verbose
178 increase the level of verbosity, (i.e. debug output). Can be
179 used multiple times to further increase verbosity. The addi‐
180 tional output is usually sent to stderr.
181 -V, --version
183 print the version string and then exit. Each utility has its own
184 version number and date of last code change.
185
187 Many utilities have command line options that take numeric arguments.
188 These numeric arguments can be large values (e.g. a logical block
189 address (LBA) on a disk) and can be inconvenient to enter in the
190 default decimal representation. So various other representations are
191 permitted.
192 Multiplicative suffixes are accepted. They are one, two or three letter
194 strings appended directly after the number to which they apply:
195 c C *1
197 w W *2
198 b B *512
199 k K KiB *1024
200 KB *1000
201 m M MiB *1048576
202 MB *1000000
203 g G GiB *(2^30)
204 GB *(10^9)
205 t T TiB *(2^40)
206 TB *(10^12)
207 p P PiB *(2^50)
208 PB *(10^15)
209 An example is "2k" for 2048. The large tera and peta suffixes are only
211 available for numeric arguments that might require 64 bits to represent
212 internally.
213 A suffix of the form "x<n>" multiplies the leading number by <n>. An
215 example is "2x33" for "66". The leading number cannot be "0" (zero) as
216 that would be interpreted as a hexadecimal number (see below).
217 These multiplicative suffixes are compatible with GNU's dd command
219 (since 2002) which claims compliance with SI and with IEC 60027-2.
220 Alternatively numerical arguments can be given in hexadecimal. There
222 are two syntaxes. The number can be preceded by either "0x" or "0X" as
223 found in the C programming language. The second hexadecimal representa‐
224 tion is a trailing "h" or "H" as found in (storage) standards. When hex
225 numbers are given, multipliers cannot be used. For example the decimal
226 value "256" can be given as "0x100" or "100h".
227
229 There are several bourne shell scripts in the 'scripts' subdirectory
230 that invoke compiled utilities (e.g. sg_readcap). The scripts start
231 with 'scsi_' rather than 'sg_'. One purpose of these scripts is to call
232 the same utility (e.g. sg_readcap) on multiple disks. Most of the basic
233 compiled utilities only allow one device as an argument. Some distribu‐
234 tions install these scripts in a visible directory (e.g. /usr/src/bin).
235 Some of these scripts have man page entries. See the README file in the
236 'scripts' subdirectory.
237 There is some example C code plus examples of complex invocations in
239 the 'examples' subdirectory. There is also a README file. The example C
240 may be a simpler example of how to use a SCSI pass-through in Linux
241 than the main utilities (found in the 'src' subdirectory). This is due
242 to the fewer abstraction layers (e.g. they don't worry the MinGW in
243 Windows may open a file in text rather than binary mode).
244 Some utilities that the author has found useful have been placed in the
246 'utils' subdirectory.
247
249 There is a web page discussing this package at
250 http://sg.danny.cz/sg/sg3_utils.html .
251
253 Written by Douglas Gilbert. Some utilities have been contributed, see
254 the CREDITS file and individual source files (in the 'src' directory).
255
257 Report bugs to <dgilbert at interlog dot com>.
258
260 Copyright © 1999-2009 Douglas Gilbert
261 Some utilities are distributed under a GPL version 2 license while oth‐
262 ers, usually more recent ones, are under a FreeBSD license. The files
263 that are common to almost all utilities and thus contain the most reus‐
264 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and
265 sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty;
266 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
267
269 sdparm(sdparm), ddpt(ddpt)
270sg3_utils-1.28 October 2009 SG3_UTILS(8)