1SG3_UTILS(8) SG3_UTILS SG3_UTILS(8)
2
6 sg3_utils - a package of utilities for sending SCSI commands
7
9 sg_* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN]
10 [--maxlen=LEN] [--raw] [--timeout=SECS] [--verbose] [--version]
11 [OTHER_OPTIONS] DEVICE
12
14 sg3_utils is a package of utilities that send SCSI commands to the
15 given DEVICE via a SCSI pass through interface provided by the host op‐
16 erating system.
17 The names of all utilities start with "sg" and most start with "sg_"
19 often followed by the name, or a shortening of the name, of the SCSI
20 command that they send. For example the "sg_verify" utility sends the
21 SCSI VERIFY command. A mapping between SCSI commands and the sg3_utils
22 utilities that issue them is shown in the COVERAGE file. The sg_raw
23 utility can be used to send an arbitrary SCSI command (supplied on the
24 command line) to the given DEVICE.
25 sg_decode_sense can be used to decode SCSI sense data given on the com‐
27 mand line or in a file. sg_raw -vvv will output the T10 name of a given
28 SCSI CDB which is most often 16 bytes or less in length.
29 SCSI draft standards can be found at http://www.t10.org . The standards
31 themselves can be purchased from ANSI and other standards organiza‐
32 tions. A good overview of various SCSI standards can be seen in
33 http://www.t10.org/scsi-3.htm with the SCSI command sets in the upper
34 part of the diagram. The highest level (i.e. most abstract) document is
35 the SCSI Architecture Model (SAM) with SAM-5 being the most recent
36 standard (ANSI INCITS 515-2016) with the most recent draft being SAM-6
37 revision 4 . SCSI commands in common with all device types can be found
38 in SCSI Primary Commands (SPC) of which SPC-4 is the most recent stan‐
39 dard (ANSI INCITS 513-2015). The most recent SPC draft is SPC-5 revi‐
40 sion 21. Block device specific commands (e.g. as used by disks) are in
41 SBC, those for tape drives in SSC, those for SCSI enclosures in SES and
42 those for CD/DVD/BD drives in MMC.
43 It is becoming more common to control ATA disks with the SCSI command
45 set. This involves the translation of SCSI commands to their corre‐
46 sponding ATA equivalents (and that is an imperfect mapping in some
47 cases). The relevant standard is called SCSI to ATA Translation (SAT,
48 SAT-2 and SAT-3) are now standards at INCITS(ANSI) and ISO while SAT-4
49 is at the draft stage. The logic to perform the command translation is
50 often called a SAT Layer or SATL and may be within an operating system,
51 in host bus adapter firmware or in an external device (e.g. associated
52 with a SAS expander). See http://www.t10.org for more information.
53 There is some support for SCSI tape devices but not for their basic op‐
55 eration. The reader is referred to the "mt" utility.
56 There are two generations of command line option usage. The newer util‐
58 ities (written since July 2004) use the getopt_long() function to parse
59 command line options. With that function, each option has two represen‐
60 tations: a short form (e.g. '-v') and a longer form (e.g. '--verbose').
61 If an argument is required then it follows a space (optionally) in the
62 short form and a "=" in the longer form (e.g. in the sg_verify utility
63 '-l 2a6h' and '--lba=2a6h' are equivalent). Note that with
64 getopt_long(), short form options can be elided, for example: '-all' is
65 equivalent to '-a -l -l'. The DEVICE argument may appear after, be‐
66 tween or prior to any options.
67 The older utilities, including as sg_inq, sg_logs, sg_modes, sg_opcode,
69 sg_rbuff, sg_readcap, sg_senddiag, sg_start and sg_turs had individual
70 command line processing code typically based on a single "-" followed
71 by one or more characters. If an argument is needed then it follows a
72 "=" ( e.g. '-p=1f' in sg_modes with its older interface). Various op‐
73 tions can be elided as long as it is not ambiguous (e.g. '-vv' to in‐
74 crease the verbosity).
75 Over time the command line interface of these older utilities became
77 messy and overloaded with options. So in sg3_utils version 1.23 the
78 command line interface of these older utilities was altered to have
79 both a cleaner getopt_long() interface and their older interface for
80 backward compatibility. By default these older utilities use their
81 getopt_long() based interface. The getopt_long() is a GNU extension
82 (i.e. not yet POSIX certified) but more recent command line utilities
83 tend to use it. That can be overridden by defining the
84 SG3_UTILS_OLD_OPTS environment variable or using '-O' or '--old' as the
85 first command line option. The man pages of the older utilities docu‐
86 ments the details.
87 Several sg3_utils utilities are based on the Unix dd command (e.g.
89 sg_dd) and permit copying data at the level of SCSI READ and WRITE com‐
90 mands. sg_dd is tightly bound to Linux and hence is not ported to other
91 OSes. A more generic utility (than sg_dd) called ddpt in a package of
92 the same name has been ported to other OSes.
93
95 The SG3_UTILS_OLD_OPTS environment variable is explained in the previ‐
96 ous section. It is only for backward compatibility of the command line
97 options for older utilities.
98 The SG3_UTILS_DSENSE environment variable may be set to a number. It is
100 only used by the embedded SNTL within the library used by the utilities
101 in this library. SNTL is a SCSI to NVMe Translation Layer. This envi‐
102 ronment variable defaults to 0 which will lead to any utility that is‐
103 sues a SCSI command that is translated to a NVMe command (by the embed‐
104 ded SNTL) that fails at the NVMe dvice, to return SCSI sense in 'fixed'
105 format. If this variable is non-zero then then the returned SCSI sense
106 will be in 'descriptor' format.
107 Several utilities have their own environment variable setting (e.g.
109 sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man pages
110 for more information.
111 There is a Linux specific environment variable called
113 SG3_UTILS_LINUX_NANO that if defined and the sg driver in the system is
114 4.0.30 or later, will show command durations in nanoseconds rather than
115 the default milliseconds. Command durations are typically only shown
116 if --verbose is used 3 or more times. Due to an interface problem (a 32
117 bit integer that should be 64 bits with the benefit of hindsight) the
118 maximum duration that can be represented in nanoseconds is about 4.2
119 seconds. If longer durations may occur then don't define this environ‐
120 ment variable (or undefine it).
121
123 Most disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc,
124 etc. SCSI disks in Linux have always had names like that but in recent
125 Linux kernels it has become more common for many other disks (including
126 SATA disks and USB storage devices) to be named like that. Partitions
127 within a disk are specified by a number appended to the device name,
128 starting at 1 (e.g. /dev/sda1 ).
129 Tape drives are named /dev/st<num> or /dev/nst<num> where <num> starts
131 at zero. Additionally one letter from this list: "lma" may be appended
132 to the name. CD, DVD and BD readers (and writers) are named
133 /dev/sr<num> where <num> start at zero. There are less used SCSI device
134 type names, the dmesg and the lsscsi commands may help to find if any
135 are attached to a running system.
136 There is also a SCSI device driver which offers alternate generic ac‐
138 cess to SCSI devices. It uses names of the form /dev/sg<num> where
139 <num> starts at zero. The "lsscsi -g" command may be useful in finding
140 these and which generic name corresponds to a device type name (e.g.
141 /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI
142 generic driver was introduced and its names are of the form
143 /dev/bsg/<h:c:t:l> where h, c, t and l are numbers. Again see the lss‐
144 csi command to find the correspondence between that SCSI tuple (i.e.
145 <h:c:t:l>) and alternate device names.
146 Prior to the Linux kernel 2.6 series these utilities could only use
148 generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux
149 kernel 2.6 series, any device name can be used by these utilities.
150 Very little has changed in Linux device naming in the Linux kernel 3
152 and 4 series.
153
155 Storage and related devices can have several device names in Windows.
156 Probably the most common in the volume name (e.g. "D:"). There are also
157 a "class" device names such as "PhysicalDrive<n>", "CDROM<n>" and
158 "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order
159 as devices are discovered (and sometimes rediscovered).
160 Some storage devices have a SCSI lower level device name which starts
162 with a SCSI (pseudo) adapter name of the form "SCSI<n>:". To this is
163 added sub-addressing in the form of a "bus" number, a "target" identi‐
164 fier and a LUN (Logical Unit Number). The "bus" number is also known as
165 a "PathId". These are assembled to form a device name of the form:
166 "SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted in
167 which case a LUN of zero is assumed. This lower level device name can‐
168 not often be used directly since Windows blocks attempts to use it if a
169 class driver has "claimed" the device. There are SCSI device types
170 (e.g. Automation/Drive interface type) for which there is no class
171 driver. At least two transports ("bus types" in Windows jargon): USB
172 and IEEE 1394 do not have a "scsi" device names of this form.
173 In keeping with DOS file system conventions, the various device names
175 can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
176 tedious to write, a shortened form of "PD<n>" is permitted by all util‐
177 ities in this package.
178 A single device (e.g. a disk) can have many device names. For example:
180 "PD0" can also be "C:", "D:" and "SCSI0:0,1,0". The two volume names
181 reflect that the disk has two partitions on it. Disk partitions that
182 are not recognized by Windows are not usually given a volume name. How‐
183 ever Vista does show a volume name for a disk which has no partitions
184 recognized by it and when selected invites the user to format it (which
185 may be rather unfriendly to other OSes).
186 These utilities assume a given device name is in the Win32 device name‐
188 space. To make that explicit "\\.\" can be prepended to the device
189 names mentioned in this section. Beware that backslash is an escape
190 character in Unix like shells and the C programming language. In a
191 shell like Msys (from MinGW) each backslash may need to be typed twice.
192 The sg_scan utility within this package lists out Windows device names
194 in a form that is suitable for other utilities in this package to use.
195
197 SCSI disks have block names of the form /dev/da<num> where <num> is an
198 integer starting at zero. The "da" is replaced by "sa" for SCSI tape
199 drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a cor‐
200 responding pass-through device name of the form /dev/pass<num> where
201 <num> is an integer starting at zero. The "camcontrol devlist" command
202 may be useful for finding out which SCSI device names are available and
203 the correspondence between class and pass-through names.
204 FreeBSD allows device names to be given without the leading "/dev/"
206 (e.g. da0 instead of /dev/da0). That worked in this package up until
207 version 1.43 when the unadorned device name (e.g. "da0") gave an error.
208 The original action (i.e. allowing unadorned device names) has been re‐
209 stored in version 1.46 . Also note that symlinks (to device names) are
210 followed before prepending "/dev/" if the resultant name doesn't start
211 with a "/".
212
214 SCSI device names below the /dev directory have a form like: c5t4d3s2
215 where the number following "c" is the controller (HBA) number, the num‐
216 ber following "t" is the target number (from the SCSI parallel inter‐
217 face days) and the number following "d" is the LUN. Following the "s"
218 is the slice number which is related to a partition and by convention
219 "s2" is the whole disk.
220 OpenSolaris also has a c5t4d3p2 form where the number following the "p"
222 is the partition number apart from "p0" which is the whole disk. So a
223 whole disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 .
224 And these device names are duplicated in the /dev/dsk and /dev/rdsk di‐
226 rectories. The former is the block device name and the latter is for
227 "raw" (or char device) access which is what sg3_utils needs. So in
228 OpenSolaris something of the form 'sg_inq /dev/rdsk/c5t4d3p0' should
229 work. If it doesn't work then add a '-vvv' option for more debug in‐
230 formation. Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk"
231 changed to "dsk") will result in an "inappropriate ioctl for device"
232 error.
233 The device names within the /dev directory are typically symbolic links
235 to much longer topological names in the /device directory. In Solaris
236 cd/dvd/bd drives seem to be treated as disks and so are found in the
237 /dev/rdsk directory. Tape drives appear in the /dev/rmt directory.
238 There is also a sgen (SCSI generic) driver which by default does not
240 attach to any device. See the /kernel/drv/sgen.conf file to control
241 what is attached. Any attached device will have a device name of the
242 form /dev/scsi/c5t4d3 .
243 Listing available SCSI devices in Solaris seems to be a challenge. "Use
245 the 'format' command" advice works but seems a very dangerous way to
246 list devices. [It does prompt again before doing any damage.] 'devfsadm
247 -Cv' cleans out the clutter in the /dev/rdsk directory, only leaving
248 what is "live". The "cfgadm -v" command looks promising.
249
251 NVMe (or NVM Express) is a relatively new storage transport and command
252 set. The level of abstraction of the NVMe command set is somewhat lower
253 the SCSI command sets, closer to the level of abstraction of ATA (and
254 SATA) command sets. NVMe claims to be designed with flash and modern
255 "solid state" storage in mind, something unheard of when SCSI was orig‐
256 inally developed in the 1980s.
257 The SCSI command sets' advantage is the length of time they have been
259 in place and the existing tools (like these) to support it. Plus SCSI
260 command sets level of abstraction is both and advantage and disadvan‐
261 tage. Recently the NVME-MI (Management Interface) designers decide to
262 use the SCSI Enclosure Services (SES-3) standard "as is" with the addi‐
263 tion of two tunnelling NVME-MI commands: SES Send and SES Receive. This
264 means after the OS interface differences are taken into account, the
265 sg_ses, sg_ses_microcode and sg_senddiag utilities can be used on a
266 NVMe device that supports a newer version of NVME-MI.
267 The NVME-MI SES Send and SES Receive commands correspond to the SCSI
269 SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands respectively.
270 There are however a few other commands that need to be translated, the
271 most important of which is the SCSI INQUIRY command to the NVMe Iden‐
272 tify controller/namespace. Starting in version 1.43 these utilities
273 contain a small SNTL (SCSI to NVMe Translation Layer) to take care of
274 these details.
275 As a side effect of this "juggling" if the sg_inq utility is used
277 (without the --page= option) on a NVMe DEVICE then the actual NVMe
278 Identifier (controller and possibly namespace) responses are decoded
279 and output. However if 'sg_inq --page=sinq <device>' is given for the
280 same DEVICE then parts of the NVMe Identify controller and namespace
281 response are translated to a SCSI standard INQUIRY response which is
282 then decoded and output.
283 Apart from the special case with the sg_inq, all other utilities in the
285 package assume they are talking to a SCSI device and decode any re‐
286 sponse accordingly. One easy way for users to see the underlying device
287 is a NVMe device is the standard INQUIRY response Vendor Identification
288 field of "NVMe " (an 8 character long string with 4 spaces to the
289 right).
290 The following SCSI commands are currently supported by the SNTL li‐
292 brary: INQUIRY, MODE SELECT(10), MODE SENSE(10), READ(10,16), READ CA‐
293 PACITY(10,16), RECEIVE DIAGNOSTIC RESULTS, REQUEST SENSE, REPORT LUNS,
294 REPORT SUPPORTED OPERATION CODES, REPORT SUPPORTED TASK MANAGEMENT
295 FUNCTIONS, SEND DIAGNOSTICS, START STOP UNIT, SYNCHRONIZE CACHE(10,16),
296 TEST UNIT READY, VERIFY(10,16), WRITE(10,16) and WRITE SAME(10,16).
297
299 To aid scripts that call these utilities, the exit status is set to in‐
300 dicate success (0) or failure (1 or more). Note that some of the lower
301 values correspond to the SCSI sense key values.
302 The exit status values listed below can be given to the sg_decode_sense
304 utility (which is found in this package) as follows:
305 sg_decode_sense --err=<exit_status>
306 and a short explanatory string will be output to stdout.
307 The exit status values are:
309 0 success. Also used for some utilities that wish to return a
311 boolean value for the "true" case (and that no error has oc‐
312 curred). The false case is conveyed by exit status 36.
313 1 syntax error. Either illegal command line options, options with
315 bad arguments or a combination of options that is not permitted.
316 2 the DEVICE reports that it is not ready for the operation re‐
318 quested. The DEVICE may be in the process of becoming ready
319 (e.g. spinning up but not at speed) so the utility may work af‐
320 ter a wait. In Linux the DEVICE may be temporarily blocked while
321 error recovery is taking place.
322 3 the DEVICE reports a medium or hardware error (or a blank
324 check). For example an attempt to read a corrupted block on a
325 disk will yield this value.
326 5 the DEVICE reports an "illegal request" with an additional sense
328 code other than "invalid command operation code". This is often
329 a supported command with a field set requesting an unsupported
330 capability. For commands that require a "service action" field
331 this value can indicate that the command with that service ac‐
332 tion value is not supported.
333 6 the DEVICE reports a "unit attention" condition. This usually
335 indicates that something unrelated to the requested command has
336 occurred (e.g. a device reset) potentially before the current
337 SCSI command was sent. The requested command has not been exe‐
338 cuted by the device. Note that unit attention conditions are
339 usually only reported once by a device.
340 7 the DEVICE reports a "data protect" sense key. This implies some
342 mechanism has blocked writes (or possibly all access to the me‐
343 dia).
344 9 the DEVICE reports an illegal request with an additional sense
346 code of "invalid command operation code" which means that it
347 doesn't support the requested command.
348 10 the DEVICE reports a "copy aborted". This implies another com‐
350 mand or device problem has stopped a copy operation. The EX‐
351 TENDED COPY family of commands (including WRITE USING TOKEN) may
352 return this sense key.
353 11 the DEVICE reports an aborted command. In some cases aborted
355 commands can be retried immediately (e.g. if the transport
356 aborted the command due to congestion).
357 14 the DEVICE reports a miscompare sense key. VERIFY and COMPARE
359 AND WRITE commands may report this.
360 15 the utility is unable to open, close or use the given DEVICE or
362 some other file. The given file name could be incorrect or there
363 may be permission problems. Adding the '-v' option may give more
364 information.
365 17 a SCSI "Illegal request" sense code received with a flag indi‐
367 cating the Info field is valid. This is often a LBA but its
368 meaning is command specific.
369 18 the DEVICE reports a medium or hardware error (or a blank check)
371 with a flag indicating the Info field is valid. This is often a
372 LBA (of the first encountered error) but its meaning is command
373 specific.
374 20 the DEVICE reports it has a check condition but "no sense" and
376 non-zero information in its additional sense codes. Some polling
377 commands (e.g. REQUEST SENSE) can receive this response. There
378 may be useful information in the sense data such as a progress
379 indication.
380 21 the DEVICE reports a "recovered error". The requested command
382 was successful. Most likely a utility will report a recovered
383 error to stderr and continue, probably leaving the utility with
384 an exit status of 0 .
385 22 the DEVICE reports that the current command or its parameters
387 imply a logical block address (LBA) that is out of range. This
388 happens surprisingly often when trying to access the last block
389 on a storage device; either a classic "off by one" logic error
390 or a misreading of the response from READ CAPACITY(10 or 16) in
391 which the address of the last block rather than the number of
392 blocks on the DEVICE is returned. Since LBAs are origin zero
393 they range from 0 to n-1 where n is the number of blocks on the
394 DEVICE, so the LBA of the last block is one less than the total
395 number of blocks.
396 24 the DEVICE reports a SCSI status of "reservation conflict". This
398 means access to the DEVICE with the current command has been
399 blocked because another machine (HBA or SCSI "initiator") holds
400 a reservation on this DEVICE. On modern SCSI systems this is re‐
401 lated to the use of the PERSISTENT RESERVATION family of com‐
402 mands.
403 25 the DEVICE reports a SCSI status of "condition met". Currently
405 only the PRE-FETCH command (see SBC-4) yields this status.
406 26 the DEVICE reports a SCSI status of "busy". SAM-6 defines this
408 status as the logical unit is temporarily unable to process a
409 command. It is recommended to re-issue the command.
410 27 the DEVICE reports a SCSI status of "task set full".
412 28 the DEVICE reports a SCSI status of "ACA active". ACA is "auto
414 contingent allegiance" and is seldom used.
415 29 the DEVICE reports a SCSI status of "task aborted". SAM-5 says:
417 "This status shall be returned if a command is aborted by a com‐
418 mand or task management function on another I_T nexus and the
419 Control mode page TAS bit is set to one".
420 31 error involving two or more command line options. They may be
422 contradicting, select an unsupported mode, or a required option
423 (given the context) is missing.
424 32 there is a logic error in the utility. It corresponds to code
426 comments like "shouldn't/can't get here". Perhaps the author
427 should be informed.
428 33 the command sent to DEVICE has timed out.
430 34 this is a Windows only exit status and indicates that the Win‐
432 dows error number (32 bits) cannot meaningfully be mapped to an
433 equivalent Unix error number returned as the exit status (7
434 bits).
435 36 no error has occurred plus the utility wants to convey a boolean
437 value of false. The corresponding true value is conveyed by a 0
438 exit status.
439 40 the command sent to DEVICE has received an "aborted command"
441 sense key with an additional sense code of 0x10. This value is
442 related to problems with protection information (PI or DIF). For
443 example this error may occur when reading a block on a drive
444 that has never been written (or is unmapped) if that drive was
445 formatted with type 1, 2 or 3 protection.
446 41 the command sent to DEVICE has received an "aborted command"
448 sense key with an additional sense code of 0x10 (as with error
449 code) plus a flag indicating the Info field is valid.
450 48 this is an internal message indicating a NVMe status field (SF)
452 is other than zero after a command has been executed (i.e. some‐
453 thing went wrong). Work in this area is currently experimental.
454 49 low level driver reports a response's residual count (i.e. num‐
456 ber of bytes actually received by HBA is 'requested_bytes -
457 residual_count') that is nonsensical.
458 50 OS system calls that fail often return a small integer number to
460 help. In Unix these are called "errno" values where 0 implies no
461 error. These error codes set aside 51 to 96 for mapping these
462 errno values but that may not be sufficient. Higher errno values
463 that cannot be mapped are all mapped to this value (i.e. 50).
464 Note that an errno value of 0 is mapped to error code 0.
465 50 + <os_error_number>
467 OS system calls that fail often return a small integer number to
468 help indicate what the error is. For example in Unix the inabil‐
469 ity of a system call to allocate memory returns (in 'errno')
470 ENOMEM which often is associated with the integer 12. So 62
471 (i.e. '50 + 12') may be returned by a utility in this case. It
472 is also possible that a utility in this package reports
473 50+ENOMEM when it can't allocate memory, not necessarily from an
474 OS system call. In recent versions of Linux the file showing the
475 mapping between symbolic constants (e.g. ENOMEM) and the corre‐
476 sponding integer is in the kernel source code file: in‐
477 clude/uapi/asm-generic/errno-base.h
478 Note that errno values that are greater than or equal to 47 can‐
479 not fit in range provided. Instead they are all mapped to 50 as
480 discussed in the previous entry.
481 97 a SCSI command response failed sanity checks.
483 98 the DEVICE reports it has a check condition but the error
485 doesn't fit into any of the above categories.
486 99 any errors that can't be categorized into values 1 to 98 may
488 yield this value. This includes transport and operating system
489 errors after the command has been sent to the device.
490 100-125
492 these error codes are used by the ddpt utility which uses the
493 sg3_utils library. They are mainly specialized error codes asso‐
494 ciated with offloaded copies.
495 126 the utility was found but could not be executed. That might oc‐
497 cur if the executable does not have execute permissions.
498 127 This is the exit status for utility not found. That might occur
500 when a script calls a utility in this package but the PATH envi‐
501 ronment variable has not been properly set up, so the script
502 cannot find the executable.
503 128 + <signum>
505 If a signal kills a utility then the exit status is 128 plus the
506 signal number. For example if a segmentation fault occurs then a
507 utility is typically killed by SIGSEGV which according to 'man 7
508 signal' has an associated signal number of 11; so the exit sta‐
509 tus will be 139 .
510 255 the utility tried to yield an exit status of 255 or larger. That
512 should not happen; given here for completeness.
513 Most of the error conditions reported above will be repeatable (an ex‐
515 ample of one that is not is "unit attention") so the utility can be run
516 again with the '-v' option (or several) to obtain more information.
517
519 Arguments to long options are mandatory for short options as well. In
520 the short form an argument to an option uses zero or more spaces as a
521 separator (i.e. the short form does not use "=" as a separator).
522 If an option takes a numeric argument then that argument is assumed to
524 be decimal unless otherwise indicated (e.g. with a leading "0x", a
525 trailing "h" or as noted in the usage message).
526 Some options are used uniformly in most of the utilities in this pack‐
528 age. Those options are listed below. Note that there are some excep‐
529 tions.
530 -d, --dry-run
532 utilities that can cause lots of user data to be lost or over‐
533 written sometimes have a --dry-run option. Device modifying ac‐
534 tions are typically bypassed (or skipped) to implement a policy
535 of "do no harm". This allows complex command line invocations
536 to be tested before the action required (e.g. format a disk) is
537 performed. The --dry-run option has become a common feature of
538 many command line utilities (e.g. the Unix 'patch' command),
539 not just those from this package.
540 Note that most hyphenated option names in this package also can
541 be given with an underscore rather than a hyphen (e.g.
542 --dry_run).
543 -e, --enumerate
545 some utilities (e.g. sg_ses and sg_vpd) store a lot of informa‐
546 tion in internal tables. This option will output that informa‐
547 tion in some readable form (e.g. sorted by an acronym or by page
548 number) then exit. Note that with this option DEVICE is ignored
549 (as are most other options) and no SCSI IO takes place, so the
550 invoker does not need any elevated permissions.
551 -h, -?, --help
553 output the usage message then exit. In a few older utilities the
554 '-h' option requests hexadecimal output. In these cases the '-?'
555 option will output the usage message then exit.
556 -H, --hex
558 for SCSI commands that yield a non-trivial response, print out
559 that response in ASCII hexadecimal. To produce hexadecimal that
560 can be parsed by other utilities (e.g. without a relative ad‐
561 dress to the left and without trailing ASCII) use this option
562 three or four times.
563 -i, --in=FN
565 many SCSI commands fetch a significant amount of data (returned
566 in the data-in buffer) which several of these utilities decode
567 (e.g. sg_vpd and sg_logs). To separate the two steps of fetching
568 the data from a SCSI device and then decoding it, this option
569 has been added. The first step (fetching the data) can be done
570 using the --hex or --raw option and redirecting the command line
571 output to a file (often done with ">" in Unix based operating
572 systems). The difference between --hex and --raw is that the
573 former produces output in ASCII hexadecimal while --raw produces
574 its output in "raw" binary.
575 The second step (i.e. decoding the SCSI response data now held
576 in a file) can be done using this --in=FN option where the file
577 name is FN. If "-" is used for FN then stdin is assumed, again
578 this allows for command line redirection (or piping). That file
579 (or stdin) is assumed to contain ASCII hexadecimal unless the
580 --raw option is also given in which case it is assumed to be bi‐
581 nary. Notice that the meaning of the --raw option is "flipped"
582 when used with --in=FN to act on the input, typically it acts on
583 the output data.
584 Since the structure of the data returned by SCSI commands varies
585 considerably then the usage information or the manpage of the
586 utility being used should be checked. In some cases --hex may
587 need to be used multiple times (and is more conveniently given
588 as '-HH' or '-HHH).
589 -i, --inhex=FN
591 This option has the same or similar functionality as --in=FN.
592 And perhaps 'inhex' is more descriptive since by default, ASCII
593 hexadecimal is expected in the contents of file: FN. Alterna‐
594 tively the short form option may be -I or -X. See the "FORMAT OF
595 FILES CONTAINING ASCII HEX" section below for more information.
596 -m, --maxlen=LEN
598 several important SCSI commands (e.g. INQUIRY and MODE SENSE)
599 have response lengths that vary depending on many factors, only
600 some of which these utilities take into account. The maximum re‐
601 sponse length is typically specified in the 'allocation length'
602 field of the cdb. In the absence of this option, several utili‐
603 ties use a default allocation length (sometimes recommended in
604 the SCSI draft standards) or a "double fetch" strategy. See
605 sg_logs(8) for its description of a "double fetch" strategy.
606 These techniques are imperfect and in the presence of faulty
607 SCSI targets can cause problems (e.g. some USB mass storage de‐
608 vices freeze if they receive an INQUIRY allocation length other
609 than 36). Also use of this option disables any "double fetch"
610 strategy that may have otherwise been used.
611 -r, --raw
613 for SCSI commands that yield a non-trivial response, output that
614 response in binary to stdout. If any error messages or warning
615 are produced they are usually sent to stderr so as to not inter‐
616 fere with the output from this option.
617 Some utilities that consume data to send to the DEVICE along
618 with the SCSI command, use this option. Alternatively the
619 --in=FN option causes DEVICE to be ignored and the response data
620 (to be decoded) fetched from a file named FN. In these cases
621 this option may indicate that binary data can be read from stdin
622 or from a nominated file (e.g. FN).
623 -t, --timeout=SECS
625 utilities that issue potentially long-running SCSI commands of‐
626 ten have a --timeout=SECS option. This typically instructs the
627 operating system to abort the SCSI command in question once the
628 timeout expires. Aborting SCSI commands is typically a messy
629 business and in the case of format like commands may leave the
630 device in a "format corrupt" state requiring another long-run‐
631 ning re-initialization command to be sent. The argument, SECS,
632 is usually in seconds and the short form of the option may be
633 something other than -t since the timeout option was typically
634 added later as storage devices grew in size and initialization
635 commands took longer. Since many utilities had relatively long
636 internal command timeouts before this option was introduced, the
637 actual command timeout given to the operating systems is the
638 higher of the internal timeout and SECS.
639 Many long running SCSI commands have an IMMED bit which causes
640 the command to finish relatively quickly but the initialization
641 process to continue. In such cases the REQUEST SENSE command can
642 be used to monitor progress with its progress indication field
643 (see the sg_requests and sg_turs utilities). Utilities that
644 send such SCSI command either have an --immed option or a --wait
645 option which is the logical inverse of the "immediate" action.
646 -v, --verbose
648 increase the level of verbosity, (i.e. debug output). Can be
649 used multiple times to further increase verbosity. The addi‐
650 tional output caused by this option is almost always sent to
651 stderr.
652 -V, --version
654 print the version string and then exit. Each utility has its own
655 version number and date of last code change.
656
658 Many utilities have command line options that take numeric arguments.
659 These numeric arguments can be large values (e.g. a logical block ad‐
660 dress (LBA) on a disk) and can be inconvenient to enter in the default
661 decimal representation. So various other representations are permitted.
662 Multiplicative suffixes are accepted. They are one, two or three letter
664 strings appended directly after the number to which they apply:
665 c C *1
667 w W *2
668 b B *512
669 k K KiB *1024
670 KB kB *1000
671 m M MiB *1048576
672 MB mB *1000000
673 g G GiB *(2^30)
674 GB gB *(10^9)
675 t T TiB *(2^40)
676 TB *(10^12)
677 p P PiB *(2^50)
678 PB *(10^15)
679 An example is "2k" for 2048. The large tera and peta suffixes are only
681 available for numeric arguments that might require 64 bits to represent
682 internally.
683 These multiplicative suffixes are compatible with GNU's dd command
685 (since 2002) which claims compliance with SI and with IEC 60027-2.
686 A suffix of the form "x<n>" multiplies the preceding number by <n>. An
688 example is "2x33" for "66". The left argument cannot be '0' as '0x'
689 will be interpreted as hexadecimal number prefix (see below). The left
690 argument to the multiplication must end in a hexadecimal digit (i.e. 0
691 to f) and the whole expression cannot have any embedded whitespace
692 (e.g. spaces). An ugly example: "0xfx0x2" for 30.
693 A suffix of the form "+<n>" adds the preceding number to <n>. An exam‐
695 ple is "3+1k" for "1027". The left argument to the addition must end in
696 a hexadecimal digit (i.e. 0 to f) and the whole expression cannot have
697 any embedded whitespace (e.g. spaces). Another example: "0xf+0x2" for
698 17.
699 Alternatively numerical arguments can be given in hexadecimal. There
701 are two syntaxes. The number can be preceded by either "0x" or "0X" as
702 found in the C programming language. The second hexadecimal representa‐
703 tion is a trailing "h" or "H" as found in (storage) standards. When hex
704 numbers are given, multipliers cannot be used. For example the decimal
705 value "256" can be given as "0x100" or "100h".
706
708 Such a file is assumed to contain a sequence of one or two digit ASCII
709 hexadecimal values separated by whitespace. "Whitespace consists of ei‐
710 ther spaces, tabs, blank lines, or any combination thereof". Each one
711 or two digit ASCII hex pair is decoded into a byte (i.e. 8 bits). The
712 following will be decoded to valid (ascending valued) bytes: '0', '01',
713 '3', 'c', 'F', '4a', 'cC', 'ff'. Lines containing only whitespace are
714 ignored. The contents of any line containing a hash mark ('#') is ig‐
715 nored from that point until the end of that line. Users are encouraged
716 to use hash marks to introduce comments in hex files. The author uses
717 the extension'.hex' on such files. Examples can be found in the 'inhex'
718 directory.
719
721 There are two standardized methods for downloading microcode (i.e. de‐
722 vice firmware) to a SCSI device. The more general way is with the SCSI
723 WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclosures
724 have their own method based on the Download microcode control/status
725 diagnostic page, see the sg_ses_microcode utility.
726
728 There are several bash shell scripts in the 'scripts' subdirectory that
729 invoke compiled utilities (e.g. sg_readcap). Several of the scripts
730 start with 'scsi_' rather than 'sg_'. One purpose of these scripts is
731 to call the same utility (e.g. sg_readcap) on multiple devices. Most of
732 the basic compiled utilities only allow one device as an argument. Some
733 distributions install these scripts in a more visible directory (e.g.
734 /usr/bin). Some of these scripts have man page entries. See the README
735 file in the 'scripts' subdirectory.
736 There is some example C code plus examples of complex invocations in
738 the 'examples' subdirectory. There is also a README file. The example C
739 may be a simpler example of how to use a SCSI pass-through in Linux
740 than the main utilities (found in the 'src' subdirectory). This is due
741 to the fewer abstraction layers (e.g. they don't worry the MinGW in
742 Windows may open a file in text rather than binary mode).
743 Some utilities that the author has found useful have been placed in the
745 'utils' subdirectory.
746
748 There is a web page discussing this package at
749 http://sg.danny.cz/sg/sg3_utils.html . The device naming used by this
750 package on various operating systems is discussed at:
751 http://sg.danny.cz/sg/device_name.html . There is a git code mirror at
752 https://github.com/hreinecke/sg3_utils . The principle code repository
753 uses subversion and is on the author's equipment. The author keeps
754 track of this via the subversion revision number which is an ascending
755 integer (currently at 774 for this package). The github mirror gets up‐
756 dated periodically from the author's repository. Depending on the time
757 of update, the above Downloads section at sg.danny.cz may be more up to
758 date than the github mirror.
759
761 Written by Douglas Gilbert. Some utilities have been contributed, see
762 the CREDITS file and individual source files (in the 'src' directory).
763
765 Report bugs to <dgilbert at interlog dot com>.
766
768 Copyright © 1999-2021 Douglas Gilbert
769 Some utilities are distributed under a GPL version 2 license while oth‐
770 ers, usually more recent ones, are under a FreeBSD license. The files
771 that are common to almost all utilities and thus contain the most reus‐
772 able code, namely sg_lib.[hc], sg_cmds_basic.[hc] and sg_cmds_ex‐
773 tra.[hc] are under a FreeBSD license. There is NO warranty; not even
774 for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
775
777 sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
778sg3_utils-1.46 March 2021 SG3_UTILS(8)