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] [--raw] [--verbose] [--version] [OTHER_OPTIONS]
10 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 com‐
19 mand that they send. For example the "sg_verify" utility sends the SCSI
20 VERIFY command. A mapping between SCSI commands and the sg3_utils util‐
21 ities 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 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 (often found at the top of the main() function) based on a
45 single "-" followed by one or more characters. If an argument is needed
46 then it follows a "=" (e.g. '-p=1f' in sg_modes). Various options can
47 be elided as long as it is not ambiguous (e.g. '-vv' to increase the
48 verbosity).
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 share dd's rather quirky command line interface.
62
64 To aid scripts that call these utilities, the exit status is set to
65 indicate success (0) or failure (1 or more). Note that some of the
66 lower values correspond to the SCSI sense key values to which they cor‐
67 respond. The exit status values are:
68 0 success
70 1 syntax error. Either illegal command line options, options with
72 bad arguments or a combination of options that is not permitted.
73 2 the DEVICE reports that it is not ready for the operation
75 requested. The device may be in the process of becoming ready
76 (e.g. spinning up but not at speed) so the utility may work
77 after a wait.
78 3 the DEVICE reports a medium or hardware error (or a blank
80 check). For example an attempt to read a corrupted block on a
81 disk will yield this value.
82 5 the DEVICE reports an "illegal request" with an additional sense
84 code other than "invalid operation code". This is often a sup‐
85 ported command with a field set requesting an unsupported capa‐
86 bility. For commands that require a "service action" field this
87 value can indicate that the command with that service action
88 value is not supported.
89 6 the DEVICE reports a "unit attention" condition. This usually
91 indicates that something unrelated to the requested command has
92 occurred (e.g. a device reset) potentially before the current
93 SCSI command was sent. The requested command has not been exe‐
94 cuted by the device. Note that unit attention conditions are
95 usually only reported once by a device.
96 9 the DEVICE reports an illegal request with an additional sense
98 code of "invalid operation code" which means that it doesn't
99 support the requested command.
100 11 the DEVICE reports an aborted command. In some cases aborted
102 commands can be retried immediately (e.g. if the transport
103 aborted the command due to congestion).
104 15 the utility is unable to open, close or use the given DEVICE.
106 The given file name could be incorrect or there may be permis‐
107 sion problems. Adding the '-v' option may give more information.
108 20 the DEVICE reports it has a check condition but "no sense" and
110 non-zero information in its additional sense codes. Some polling
111 commands (e.g. REQUEST SENSE) can receive this response.
112 21 the DEVICE reports a "recovered error". The requested command
114 was successful. Most likely a utility will report a recovered
115 error to stderr and continue, probably leaving the utility with
116 an exit status of 0 .
117 33 the command sent to DEVICE has timed out.
119 97 the response to a SCSI command failed sanity checks.
121 98 the DEVICE reports it has a check condition but the error
123 doesn't fit into any of the above categories.
124 99 any errors that can't be categorized into values 1 to 98 may
126 yield this value. This includes transport and operating system
127 errors after the command has been sent to the device.
128 Most of the error conditions reported above will be repeatable (an
130 example of one that is not is "unit attention") so the utility can be
131 run again with the '-v' option (or several) to obtain more information.
132
134 Arguments to long options are mandatory for short options as well. In
135 the short form an argument to an option uses zero or more spaces as a
136 separator (i.e. the short form does not use "=" as a separator).
137 If an option takes a numeric argument then that argument is assumed to
139 be decimal unless otherwise indicated (e.g. with a leading "0x", a
140 trailing "h" or as noted in the usage message).
141 -h, -?, --help
143 output the usage message then exit. In a few older utilities the
144 '-h' option requests hexadecimal output. In these cases the '-?'
145 option will output the usage message then exit.
146 -H, --hex
148 for SCSI commands that yield a non-trivial response, print out
149 that response in ASCII hexadecimal.
150 -r, --raw
152 for SCSI commands that yield a non-trivial response, output that
153 response in binary to stdout. If any error messages or warning
154 are produced they are usually sent to stderr. Some utilities
155 that consume data to send to the device along with the SCSI com‐
156 mand, use this option to provide that data or indicate that it
157 can be read from stdin.
158 -v, --verbose
160 increase the level of verbosity, (i.e. debug output). Can be
161 used multiple times to further increase verbosity. The addi‐
162 tional output is usually sent to stderr.
163 -V, --version
165 print the version string and then exit. Each utility has its own
166 version number and date of last code change.
167
169 Written by Douglas Gilbert.
170
172 Report bugs to <dgilbert at interlog dot com>.
173
175 Copyright © 1999-2007 Douglas Gilbert
176 Some utilities are distributed under a GPL version 2 license while oth‐
177 ers, usually more recent ones, are under a FreeBSD license. The files
178 that are common to almost all utilities and thus contain the most reus‐
179 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and
180 sg_cmds_extra.[hc] are under a FreeBSD license. There is NO warranty;
181 not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
182
184 sdparm(sdparm)
185sg3_utils-1.23 Jamuary 2007 SG3_UTILS(8)