File: sg3_utils.8

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