1SG3_UTILS(8)                       SG3_UTILS                      SG3_UTILS(8)
2
3
4

NAME

6       sg3_utils - a package of utilities for sending SCSI commands
7

SYNOPSIS

9       sg_*    [--dry-run]    [--enumerate]    [--help]    [--hex]   [--in=FN]
10       [--maxlen=LEN]   [--raw]   [--timeout=SECS]   [--verbose]   [--version]
11       [OTHER_OPTIONS] DEVICE
12

DESCRIPTION

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
16       operating system.
17
18       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
26       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
30       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  19. 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
44       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
54       There  is  some  support  for SCSI tape devices but not for their basic
55       operation. The reader is referred to the "mt" utility.
56
57       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,
66       between or prior to any options.
67
68       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
73       options can be elided as long as it is not  ambiguous  (e.g.  '-vv'  to
74       increase the verbosity).
75
76       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
88       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

ENVIRONMENT VARIABLES

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
99       The  SG3_UTILS_DSENSE  environment  variable may be set to a number. If
100       that number is non-zero then descriptor sense is set in the  SNTL  (the
101       small SCSI to NVMe Translation Layer within the underlying library).
102
103       Several  utilities  have  their  own environment variable setting (e.g.
104       sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man  pages
105       for more information.
106

LINUX DEVICE NAMING

108       Most  disk  block devices have names like /dev/sda, /dev/sdb, /dev/sdc,
109       etc.  SCSI disks in Linux have always had names like that but in recent
110       Linux kernels it has become more common for many other disks (including
111       SATA disks and USB storage devices) to be named like  that.  Partitions
112       within  a  disk  are specified by a number appended to the device name,
113       starting at 1 (e.g. /dev/sda1 ).
114
115       Tape drives are named /dev/st<num> or /dev/nst<num> where <num>  starts
116       at  zero. Additionally one letter from this list: "lma" may be appended
117       to  the  name.  CD,  DVD  and  BD  readers  (and  writers)  are   named
118       /dev/sr<num> where <num> start at zero. There are less used SCSI device
119       type names, the dmesg and the lsscsi commands may help to find  if  any
120       are attached to a running system.
121
122       There  is  also  a  SCSI  device  driver which offers alternate generic
123       access to SCSI devices. It uses names of the  form  /dev/sg<num>  where
124       <num>  starts at zero. The "lsscsi -g" command may be useful in finding
125       these and which generic name corresponds to a device  type  name  (e.g.
126       /dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI
127       generic  driver  was  introduced  and  its  names  are  of   the   form
128       /dev/bsg/<h:c:t:l>  where h, c, t and l are numbers. Again see the lss‐
129       csi command to find the correspondence between that  SCSI  tuple  (i.e.
130       <h:c:t:l>) and alternate device names.
131
132       Prior  to  the  Linux  kernel 2.6 series these utilities could only use
133       generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux
134       kernel 2.6 series, any device name can be used by these utilities.
135
136       Very  little  has  changed in Linux device naming in the Linux kernel 3
137       and 4 series.
138

WINDOWS DEVICE NAMING

140       Storage and related devices can have several device names  in  Windows.
141       Probably the most common in the volume name (e.g. "D:"). There are also
142       a "class" device  names  such  as  "PhysicalDrive<n>",  "CDROM<n>"  and
143       "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order
144       as devices are discovered (and sometimes rediscovered).
145
146       Some storage devices have a SCSI lower level device name  which  starts
147       with  a  SCSI  (pseudo) adapter name of the form "SCSI<n>:". To this is
148       added sub-addressing in the form of a "bus" number, a "target"  identi‐
149       fier and a LUN (Logical Unit Number). The "bus" number is also known as
150       a "PathId".  These are assembled to form a device  name  of  the  form:
151       "SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted in
152       which case a LUN of zero is assumed. This lower level device name  can‐
153       not often be used directly since Windows blocks attempts to use it if a
154       class driver has "claimed" the device.  There  are  SCSI  device  types
155       (e.g.   Automation/Drive  interface  type)  for which there is no class
156       driver. At least two transports ("bus types" in  Windows  jargon):  USB
157       and IEEE 1394 do not have a "scsi" device names of this form.
158
159       In  keeping  with DOS file system conventions, the various device names
160       can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is
161       tedious to write, a shortened form of "PD<n>" is permitted by all util‐
162       ities in this package.
163
164       A single device (e.g. a disk) can have many device names. For  example:
165       "PD0"  can  also  be "C:", "D:" and "SCSI0:0,1,0". The two volume names
166       reflect that the disk has two partitions on it.  Disk  partitions  that
167       are not recognized by Windows are not usually given a volume name. How‐
168       ever Vista does show a volume name for a disk which has  no  partitions
169       recognized by it and when selected invites the user to format it (which
170       may be rather unfriendly to other OSes).
171
172       These utilities assume a given device  name  is  in  the  Win32  device
173       namespace.  To make that explicit "\\.\" can be prepended to the device
174       names mentioned in this section. Beware that  backslash  is  an  escape
175       character  in  Unix  like  shells  and the C programming language. In a
176       shell like Msys (from MinGW) each backslash may need to be typed twice.
177
178       The sg_scan utility within this package lists out Windows device  names
179       in a form that is suitable for other utilities in this package to use.
180

FREEBSD DEVICE NAMING

182       SCSI  disks have block names of the form /dev/da<num> where <num> is an
183       integer starting at zero. The "da" is replaced by "sa"  for  SCSI  tape
184       drives  and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a cor‐
185       responding pass-through device name of the  form  /dev/pass<num>  where
186       <num>  is an integer starting at zero. The "camcontrol devlist" command
187       may be useful for finding out which SCSI device names are available and
188       the correspondence between class and pass-through names.
189

SOLARIS DEVICE NAMING

191       SCSI  device  names below the /dev directory have a form like: c5t4d3s2
192       where the number following "c" is the controller (HBA) number, the num‐
193       ber  following  "t" is the target number (from the SCSI parallel inter‐
194       face days) and the number following "d" is the LUN. Following  the  "s"
195       is  the  slice number which is related to a partition and by convention
196       "s2" is the whole disk.
197
198       OpenSolaris also has a c5t4d3p2 form where the number following the "p"
199       is  the  partition number apart from "p0" which is the whole disk. So a
200       whole disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 .
201
202       And these device names are duplicated in  the  /dev/dsk  and  /dev/rdsk
203       directories.  The former is the block device name and the latter is for
204       "raw" (or char device) access which is  what  sg3_utils  needs.  So  in
205       OpenSolaris  something  of  the form 'sg_inq /dev/rdsk/c5t4d3p0' should
206       work.  If it doesn't work then add  a  '-vvv'  option  for  more  debug
207       information.   Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk"
208       changed to "dsk") will result in an "inappropriate  ioctl  for  device"
209       error.
210
211       The device names within the /dev directory are typically symbolic links
212       to much longer topological names in the /device directory.  In  Solaris
213       cd/dvd/bd  drives  seem  to be treated as disks and so are found in the
214       /dev/rdsk directory. Tape drives appear in the /dev/rmt directory.
215
216       There is also a sgen (SCSI generic) driver which by  default  does  not
217       attach  to  any  device.  See the /kernel/drv/sgen.conf file to control
218       what is attached. Any attached device will have a device  name  of  the
219       form /dev/scsi/c5t4d3 .
220
221       Listing available SCSI devices in Solaris seems to be a challenge. "Use
222       the 'format' command" advice works but seems a very  dangerous  way  to
223       list devices. [It does prompt again before doing any damage.] 'devfsadm
224       -Cv' cleans out the clutter in the /dev/rdsk  directory,  only  leaving
225       what is "live". The "cfgadm -v" command looks promising.
226

NVME SUPPORT

228       NVMe (or NVM Express) is a relatively new storage transport and command
229       set. The level of abstraction of the NVMe command set is somewhat lower
230       the  SCSI  command sets, closer to the level of abstraction of ATA (and
231       SATA) command sets. NVMe claims to be designed with  flash  and  modern
232       "solid state" storage in mind, something unheard of when SCSI was orig‐
233       inally developed in the 1980s.
234
235       The SCSI command sets' advantage is the length of time they  have  been
236       in  place  and the existing tools (like these) to support it. Plus SCSI
237       command sets level of abstraction is both and advantage  and  disadvan‐
238       tage.  Recently  the NVME-MI (Management Interface) designers decide to
239       use the SCSI Enclosure Services (SES-3) standard "as is" with the addi‐
240       tion of two tunnelling NVME-MI commands: SES Send and SES Receive. This
241       means after the OS interface differences are taken  into  account,  the
242       sg_ses,  sg_ses_microcode  and  sg_senddiag  utilities can be used on a
243       NVMe device that supports a newer version of NVME-MI.
244
245       The NVME-MI SES Send and SES Receive commands correspond  to  the  SCSI
246       SEND  DIAGNOSTIC  and RECEIVE DIAGNOSTIC RESULTS commands respectively.
247       There are however a few other commands that need to be translated,  the
248       most  important  of which is the SCSI INQUIRY command to the NVMe Iden‐
249       tify controller/namespace. Version 1.43 of these  utilities  contain  a
250       small  SNTL  (SCSI  to  NVMe  Translation  Layer) to take care of these
251       details.
252
253       As a side effect of this "juggling"  if  the  sg_inq  utility  is  used
254       (without  the  --page=  option)  on  a NVMe DEVICE then the actual NVMe
255       Identifier (controller and possibly namespace)  responses  are  decoded
256       and  output.  However if 'sg_inq --page=sinq <device>' is given for the
257       same DEVICE then parts of the NVMe Identify  controller  and  namespace
258       response  are  translated  to a SCSI standard INQUIRY response which is
259       then decoded and output.
260
261       Apart from the special case with the sg_inq, all other utilities in the
262       package  assume  they  are  talking  to  a  SCSI  device and decode any
263       response accordingly. One easy way for  users  to  see  the  underlying
264       device is a NVMe device is the standard INQUIRY response Vendor Identi‐
265       fication field of "NVMe    " (an 8 character long string with 4  spaces
266       to the right).
267

EXIT STATUS

269       To  aid  scripts  that  call these utilities, the exit status is set to
270       indicate success (0) or failure (1 or more).  Note  that  some  of  the
271       lower values correspond to the SCSI sense key values.
272
273       The exit status values listed below can be given to the sg_decode_sense
274       utility (which is found in this package) as follows:
275         sg_decode_sense --err=<exit_status>
276       and a short explanatory string will be output to stdout.
277
278       The exit status values are:
279
280       0      success. Also used for some utilities  that  wish  to  return  a
281              boolean  value  for  the  "true"  case  (and  that  no error has
282              occurred). The false case is conveyed by exit status 36.
283
284       1      syntax error. Either illegal command line options, options  with
285              bad arguments or a combination of options that is not permitted.
286
287       2      the  DEVICE  reports  that  it  is  not  ready for the operation
288              requested.  The DEVICE may be in the process of  becoming  ready
289              (e.g.   spinning  up  but  not at speed) so the utility may work
290              after a wait. In Linux the DEVICE  may  be  temporarily  blocked
291              while error recovery is taking place.
292
293       3      the  DEVICE  reports  a  medium  or  hardware  error (or a blank
294              check). For example an attempt to read a corrupted  block  on  a
295              disk will yield this value.
296
297       5      the DEVICE reports an "illegal request" with an additional sense
298              code other than "invalid command operation code". This is  often
299              a  supported  command with a field set requesting an unsupported
300              capability. For commands that require a "service  action"  field
301              this  value  can  indicate  that  the  command with that service
302              action value is not supported.
303
304       6      the DEVICE reports a "unit attention"  condition.  This  usually
305              indicates  that something unrelated to the requested command has
306              occurred (e.g. a device reset) potentially  before  the  current
307              SCSI  command  was sent. The requested command has not been exe‐
308              cuted by the device. Note that  unit  attention  conditions  are
309              usually only reported once by a device.
310
311       7      the DEVICE reports a "data protect" sense key. This implies some
312              mechanism has blocked writes (or  possibly  all  access  to  the
313              media).
314
315       9      the  DEVICE  reports an illegal request with an additional sense
316              code of "invalid command operation code"  which  means  that  it
317              doesn't support the requested command.
318
319       10     the  DEVICE  reports a "copy aborted". This implies another com‐
320              mand or  device  problem  has  stopped  a  copy  operation.  The
321              EXTENDED  COPY  family of commands (including WRITE USING TOKEN)
322              may return this sense key.
323
324       11     the DEVICE reports an aborted command.  In  some  cases  aborted
325              commands  can  be  retried  immediately  (e.g.  if the transport
326              aborted the command due to congestion).
327
328       14     the DEVICE reports a miscompare sense key.  VERIFY  and  COMPARE
329              AND WRITE commands may report this.
330
331       15     the  utility is unable to open, close or use the given DEVICE or
332              some other file. The given file name could be incorrect or there
333              may be permission problems. Adding the '-v' option may give more
334              information.
335
336       17     a SCSI "Illegal request" sense code received with a  flag  indi‐
337              cating  the  Info  field  is  valid. This is often a LBA but its
338              meaning is command specific.
339
340       18     the DEVICE reports a medium or hardware error (or a blank check)
341              with  a flag indicating the Info field is valid. This is often a
342              LBA (of the first encountered error) but its meaning is  command
343              specific.
344
345       20     the  DEVICE  reports it has a check condition but "no sense" and
346              non-zero information in its additional sense codes. Some polling
347              commands  (e.g.  REQUEST SENSE) can receive this response. There
348              may be useful information in the sense data such as  a  progress
349              indication.
350
351       21     the  DEVICE  reports  a "recovered error". The requested command
352              was successful. Most likely a utility will  report  a  recovered
353              error  to stderr and continue, probably leaving the utility with
354              an exit status of 0 .
355
356       22     the DEVICE reports that the current command  or  its  parameters
357              imply  a  logical block address (LBA) that is out of range. This
358              happens surprisingly often when trying to access the last  block
359              on  a  storage device; either a classic "off by one" logic error
360              or a misreading of the response from READ CAPACITY(10 or 16)  in
361              which  the  address  of the last block rather than the number of
362              blocks on the DEVICE is returned. Since  LBAs  are  origin  zero
363              they  range from 0 to n-1 where n is the number of blocks on the
364              DEVICE, so the LBA of the last block is one less than the  total
365              number of blocks.
366
367       24     the DEVICE reports a SCSI status of "reservation conflict". This
368              means access to the DEVICE with the  current  command  has  been
369              blocked  because another machine (HBA or SCSI "initiator") holds
370              a reservation on this DEVICE. On modern  SCSI  systems  this  is
371              related  to the use of the PERSISTENT RESERVATION family of com‐
372              mands.
373
374       25     the DEVICE reports a SCSI status of "condition  met".  Currently
375              only the PRE-FETCH command (see SBC-4) yields this status.
376
377       26     the  DEVICE  reports a SCSI status of "busy". SAM-6 defines this
378              status as the logical unit is temporarily unable  to  process  a
379              command. It is recommended to re-issue the command.
380
381       27     the DEVICE reports a SCSI status of "task set full".
382
383       28     the  DEVICE  reports a SCSI status of "ACA active". ACA is "auto
384              contingent allegiance" and is seldom used.
385
386       29     the DEVICE reports a SCSI status of "task aborted". SAM-5  says:
387              "This status shall be returned if a command is aborted by a com‐
388              mand or task management function on another I_T  nexus  and  the
389              Control mode page TAS bit is set to one".
390
391       31     error  involving  two  or more command line options. They may be
392              contradicting, select an unsupported mode, or a required  option
393              (given the context) is missing.
394
395       32     there  is  a  logic error in the utility. It corresponds to code
396              comments like "shouldn't/can't get  here".  Perhaps  the  author
397              should be informed.
398
399       33     the command sent to DEVICE has timed out.
400
401       36     no error has occurred plus the utility wants to convey a boolean
402              value of false. The corresponding true value is conveyed by a  0
403              exit status.
404
405       40     the  command  sent  to  DEVICE has received an "aborted command"
406              sense key with an additional sense code of 0x10. This  group  is
407              related to problems with protection information (PI or DIF). For
408              example this error may occur when reading a  block  on  a  drive
409              that  has  never been written (or is unmapped) if that drive was
410              formatted with type 1, 2 or 3 protection.
411
412       41     the command sent to DEVICE has  received  an  "aborted  command"
413              sense  key  with an additional sense code of 0x10 (as with error
414              code) plus a flag indicating the Info field is valid.
415
416       48     this is an internal message indicating a NVMe status field  (SF)
417              is other than zero after a command has been executed (i.e. some‐
418              thing went wrong).  Work in this area is currently experimental.
419
420       49     low level driver reports a response's residual count (i.e.  num‐
421              ber  of  bytes  actually  received  by HBA is 'requested_bytes -
422              residual_count') that is
423
424       50     OS system calls that fail often return a small integer number to
425              help. In Unix these are called "errno" values where 0 implies no
426              error. These error codes set aside 51 to 96  for  mapping  these
427              errno values but that may not be sufficient. Higher errno values
428              that cannot be mapped are all mapped to this value (i.e. 50).
429              Note that an errno value of 0 is mapped to error code 0.
430
431       50 + <os_error_number>
432              OS system calls that fail often return a small integer number to
433              help indicate what the error is. For example in Unix the inabil‐
434              ity of a system call to allocate  memory  returns  (in  'errno')
435              ENOMEM  which  often  is  associated  with the integer 12. So 62
436              (i.e. '50 + 12') may be returned by a utility in this  case.  It
437              is  also  possible  that  a  utility  in  this  package  reports
438              50+ENOMEM when it can't allocate memory, not necessarily from an
439              OS system call. In recent versions of Linux the file showing the
440              mapping between symbolic constants (e.g. ENOMEM) and the  corre‐
441              sponding   integer   is   in   the   kernel  source  code  file:
442              include/uapi/asm-generic/errno-base.h
443              Note that errno values that are greater than or equal to 47 can‐
444              not  fit in range provided. Instead they are all mapped to 50 as
445              discussed in the previous entry.
446
447       97     a SCSI command response failed sanity checks.
448
449       98     the DEVICE reports it  has  a  check  condition  but  the  error
450              doesn't fit into any of the above categories.
451
452       99     any  errors  that  can't  be categorized into values 1 to 98 may
453              yield this value. This includes transport and  operating  system
454              errors after the command has been sent to the device.
455
456       100-125
457              these  error  codes  are used by the ddpt utility which uses the
458              sg3_utils library. They are mainly specialized error codes asso‐
459              ciated with offloaded copies.
460
461       126    the  utility  was  found  but  could not be executed. That might
462              occur if the executable does not have execute permissions.
463
464       127    This is the exit status for utility not found. That might  occur
465              when a script calls a utility in this package but the PATH envi‐
466              ronment variable has not been properly set  up,  so  the  script
467              cannot find the executable.
468
469       128 + <signum>
470              If a signal kills a utility then the exit status is 128 plus the
471              signal number. For example if a segmentation fault occurs then a
472              utility is typically killed by SIGSEGV which according to 'man 7
473              signal' has an associated signal number of 11; so the exit  sta‐
474              tus will be 139 .
475
476       255    the utility tried to yield an exit status of 255 or larger. That
477              should not happen; given here for completeness.
478
479       Most of the error conditions reported  above  will  be  repeatable  (an
480       example  of  one that is not is "unit attention") so the utility can be
481       run again with the '-v' option (or several) to obtain more information.
482

COMMON OPTIONS

484       Arguments to long options are mandatory for short options as  well.  In
485       the  short  form an argument to an option uses zero or more spaces as a
486       separator (i.e. the short form does not use "=" as a separator).
487
488       If an option takes a numeric argument then that argument is assumed  to
489       be  decimal  unless  otherwise  indicated  (e.g. with a leading "0x", a
490       trailing "h" or as noted in the usage message).
491
492       Some options are used uniformly in most of the utilities in this  pack‐
493       age.  Those  options  are listed below. Note that there are some excep‐
494       tions.
495
496       -d, --dry-run
497              utilities that can cause lots of user data to be lost  or  over‐
498              written  sometimes  have  a  --dry-run  option. Device modifying
499              actions are typically bypassed (or skipped) to implement a  pol‐
500              icy  of  "do no harm".  This allows complex command line invoca‐
501              tions to be tested before the action  required  (e.g.  format  a
502              disk)  is  performed.  The  --dry-run option has become a common
503              feature of many command line utilities (e.g.  the  Unix  'patch'
504              command), not just those from this package.
505              Note  that most hyphenated option names in this package also can
506              be  given  with  an  underscore  rather  than  a  hyphen   (e.g.
507              --dry_run).
508
509       -e, --enumerate
510              some  utilities (e.g. sg_ses and sg_vpd) store a lot of informa‐
511              tion in internal tables. This option will output  that  informa‐
512              tion in some readable form (e.g. sorted by an acronym or by page
513              number) then exit. Note that with this option DEVICE is  ignored
514              (as  are  most other options) and no SCSI IO takes place, so the
515              invoker does not need any elevated permissions.
516
517       -h, -?, --help
518              output the usage message then exit. In a few older utilities the
519              '-h' option requests hexadecimal output. In these cases the '-?'
520              option will output the usage message then exit.
521
522       -H, --hex
523              for SCSI commands that yield a non-trivial response,  print  out
524              that  response in ASCII hexadecimal. To produce hexadecimal that
525              can be parsed  by  other  utilities  (e.g.  without  a  relative
526              address  to the left and without trailing ASCII) use this option
527              three or four times.
528
529       -i, --in=FN
530              many SCSI commands fetch a significant amount of data  (returned
531              in  the  data-in buffer) which several of these utilities decode
532              (e.g. sg_vpd and sg_logs). To separate the two steps of fetching
533              the  data  from  a SCSI device and then decoding it, this option
534              has been added. The first step (fetching the data) can  be  done
535              using the --hex or --raw option and redirecting the command line
536              output to a file (often done with ">" in  Unix  based  operating
537              systems).  The  difference  between  --hex and --raw is that the
538              former produces output in ASCII hexadecimal while --raw produces
539              its output in "raw" binary.
540              The  second  step (i.e. decoding the SCSI response data now held
541              in a file) can be done using this --in=FN option where the  file
542              name  is  FN. If "-" is used for FN then stdin is assumed, again
543              this allows for command line redirection (or piping). That  file
544              (or  stdin)  is  assumed to contain ASCII hexadecimal unless the
545              --raw option is also given in which case it  is  assumed  to  be
546              binary. Notice that the meaning of the --raw option is "flipped"
547              when used with --in=FN to act on the input, typically it acts on
548              the output data.
549              Since the structure of the data returned by SCSI commands varies
550              considerably then the usage information or the  manpage  of  the
551              utility  being  used  should be checked. In some cases --hex may
552              need to be used multiple times (and is more  conveniently  given
553              as  '-HH'  or  '-HHH). In other cases the name of this option is
554              --inhex=FN.
555
556       -m, --maxlen=LEN
557              several important SCSI commands (e.g. INQUIRY  and  MODE  SENSE)
558              have  response lengths that vary depending on many factors, only
559              some of which these utilities take  into  account.  The  maximum
560              response  length  is  typically  specified  in  the  'allocation
561              length' field of the cdb. In the absence of this option, several
562              utilities use a default allocation length (sometimes recommended
563              in the SCSI draft standards) or a "double fetch" strategy.   See
564              sg_logs(8)  for  its  description  of a "double fetch" strategy.
565              These techniques are imperfect and in  the  presence  of  faulty
566              SCSI  targets  can  cause  problems  (e.g. some USB mass storage
567              devices freeze if they  receive  an  INQUIRY  allocation  length
568              other  than  36).  Also  use of this option disables any "double
569              fetch" strategy that may have otherwise been used.
570
571       -r, --raw
572              for SCSI commands that yield a non-trivial response, output that
573              response  in  binary to stdout. If any error messages or warning
574              are produced they are usually sent to stderr so as to not inter‐
575              fere with the output from this option.
576              Some  utilities  that  consume  data to send to the DEVICE along
577              with the  SCSI  command,  use  this  option.  Alternatively  the
578              --in=FN option causes DEVICE to be ignored and the response data
579              (to be decoded) fetched from a file named  FN.  In  these  cases
580              this option may indicate that binary data can be read from stdin
581              or from a nominated file (e.g. FN).
582
583       -t, --timeout=SECS
584              utilities that  issue  potentially  long-running  SCSI  commands
585              often have a --timeout=SECS option. This typically instructs the
586              operating system to abort the SCSI command in question once  the
587              timeout  expires.  Aborting  SCSI  commands is typically a messy
588              business and in the case of format like commands may  leave  the
589              device  in  a "format corrupt" state requiring another long-run‐
590              ning re-initialization command to be sent. The  argument,  SECS,
591              is  usually  in  seconds and the short form of the option may be
592              something other than -t since the timeout option  was  typically
593              added  later  as storage devices grew in size and initialization
594              commands took longer. Since many utilities had  relatively  long
595              internal command timeouts before this option was introduced, the
596              actual command timeout given to the  operating  systems  is  the
597              higher of the internal timeout and SECS.
598              Many  long  running SCSI commands have an IMMED bit which causes
599              the command to finish relatively quickly but the  initialization
600              process to continue. In such cases the REQUEST SENSE command can
601              be used to monitor progress with its progress  indication  field
602              (see  the  sg_requests  and  sg_turs utilities).  Utilities that
603              send such SCSI command either have an --immed option or a --wait
604              option which is the logical inverse of the "immediate" action.
605
606       -v, --verbose
607              increase  the  level  of  verbosity, (i.e. debug output). Can be
608              used multiple times to further  increase  verbosity.  The  addi‐
609              tional  output  caused  by  this option is almost always sent to
610              stderr.
611
612       -V, --version
613              print the version string and then exit. Each utility has its own
614              version number and date of last code change.
615

NUMERIC ARGUMENTS

617       Many  utilities  have command line options that take numeric arguments.
618       These numeric arguments can be  large  values  (e.g.  a  logical  block
619       address  (LBA)  on  a  disk)  and  can  be inconvenient to enter in the
620       default decimal representation. So various  other  representations  are
621       permitted.
622
623       Multiplicative suffixes are accepted. They are one, two or three letter
624       strings appended directly after the number to which they apply:
625
626          c C         *1
627          w W         *2
628          b B         *512
629          k K KiB     *1024
630          KB kB       *1000
631          m M MiB     *1048576
632          MB mB       *1000000
633          g G GiB     *(2^30)
634          GB gB       *(10^9)
635          t T TiB     *(2^40)
636          TB          *(10^12)
637          p P PiB     *(2^50)
638          PB          *(10^15)
639
640       An example is "2k" for 2048. The large tera and peta suffixes are  only
641       available for numeric arguments that might require 64 bits to represent
642       internally.
643
644       A suffix of the form "x<n>" multiplies the leading number  by  <n>.  An
645       example  is "2x33" for "66". The leading number cannot be "0" (zero) as
646       that would be interpreted as a hexadecimal number (see below).
647
648       These multiplicative suffixes are  compatible  with  GNU's  dd  command
649       (since 2002) which claims compliance with SI and with IEC 60027-2.
650
651       Alternatively  numerical  arguments  can be given in hexadecimal. There
652       are two syntaxes. The number can be preceded by either "0x" or "0X"  as
653       found in the C programming language. The second hexadecimal representa‐
654       tion is a trailing "h" or "H" as found in (storage) standards. When hex
655       numbers  are given, multipliers cannot be used. For example the decimal
656       value "256" can be given as "0x100" or "100h".
657

MICROCODE AND FIRMWARE

659       There are two standardized  methods  for  downloading  microcode  (i.e.
660       device  firmware)  to  a  SCSI device. The more general way is with the
661       SCSI WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclo‐
662       sures  have  their  own  method  based  on  the Download microcode con‐
663       trol/status diagnostic page, see the sg_ses_microcode utility.
664

SCRIPTS, EXAMPLES and UTILS

666       There are several bash shell scripts in the 'scripts' subdirectory that
667       invoke  compiled  utilities  (e.g.  sg_readcap). Several of the scripts
668       start with 'scsi_' rather than 'sg_'. One purpose of these  scripts  is
669       to call the same utility (e.g. sg_readcap) on multiple devices. Most of
670       the basic compiled utilities only allow one device as an argument. Some
671       distributions  install  these scripts in a more visible directory (e.g.
672       /usr/bin). Some of these scripts have man page entries. See the  README
673       file in the 'scripts' subdirectory.
674
675       There  is  some  example C code plus examples of complex invocations in
676       the 'examples' subdirectory. There is also a README file. The example C
677       may  be  a  simpler  example of how to use a SCSI pass-through in Linux
678       than the main utilities (found in the 'src' subdirectory). This is  due
679       to  the  fewer  abstraction  layers (e.g. they don't worry the MinGW in
680       Windows may open a file in text rather than binary mode).
681
682       Some utilities that the author has found useful have been placed in the
683       'utils' subdirectory.
684

WEB SITE

686       There     is    a    web    page    discussing    this    package    at
687       http://sg.danny.cz/sg/sg3_utils.html . The device naming used  by  this
688       package    on    various    operating    systems   is   discussed   at:
689       http://sg.danny.cz/sg/device_name.html . There is a git code mirror  at
690       https://github.com/hreinecke/sg3_utils  . The principle code repository
691       uses subversion and is on the  author's  equipment.  The  author  keeps
692       track  of this via the subversion revision number which is an ascending
693       integer (currently at 774 for this package).  The  github  mirror  gets
694       updated  periodically  from  the  author's repository. Depending on the
695       time of update, the above Downloads section at sg.danny.cz may be  more
696       up to date than the github mirror.
697

AUTHORS

699       Written  by  Douglas Gilbert. Some utilities have been contributed, see
700       the CREDITS file and individual source files (in the 'src' directory).
701

REPORTING BUGS

703       Report bugs to <dgilbert at interlog dot com>.
704
706       Copyright © 1999-2018 Douglas Gilbert
707       Some utilities are distributed under a GPL version 2 license while oth‐
708       ers,  usually  more recent ones, are under a FreeBSD license. The files
709       that are common to almost all utilities and thus contain the most reus‐
710       able     code,     namely     sg_lib.[hc],    sg_cmds_basic.[hc]    and
711       sg_cmds_extra.[hc] are under a FreeBSD license. There is  NO  warranty;
712       not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
713

SEE ALSO

715       sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)
716
717
718
719sg3_utils-1.44                  September 2018                    SG3_UTILS(8)
Impressum