1Content-type: text/html; charset=UTF-8 2 3<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 4<HTML><HEAD><TITLE>Man page of SG3_UTILS</TITLE> 5</HEAD><BODY> 6<H1>SG3_UTILS</H1> 7Section: SG3_UTILS (8)<BR>Updated: November 2021<BR><A HREF="#index">Index</A> 8<A HREF="../index.html">Return to Main Contents</A><HR> 9 10<A NAME="lbAB"> </A> 11<H2>NAME</H2> 12 13sg3_utils - a package of utilities for sending SCSI commands 14<A NAME="lbAC"> </A> 15<H2>SYNOPSIS</H2> 16 17<B>sg_*</B> 18 19[<I>--dry-run</I>] [<I>--enumerate</I>] [<I>--help</I>] [<I>--hex</I>] 20[<I>--in=FN</I>] [<I>--inhex=FN</I>] [<I>--maxlen=LEN</I>] [<I>--raw</I>] 21[<I>--timeout=SECS</I>] [<I>--verbose</I>] [<I>--version</I>] 22[<I>OTHER_OPTIONS</I>] <I>DEVICE</I> 23<A NAME="lbAD"> </A> 24<H2>DESCRIPTION</H2> 25 26 27<P> 28 29sg3_utils is a package of utilities that send SCSI commands to the given 30<I>DEVICE</I> via a SCSI pass through interface provided by the host 31operating system. 32<P> 33 34The names of all utilities start with "sg" and most start with "sg_" often 35followed by the name, or a shortening of the name, of the SCSI command that 36they send. For example the "sg_verify" utility sends the SCSI VERIFY 37command. A mapping between SCSI commands and the sg3_utils utilities that 38issue them is shown in the COVERAGE file. The sg_raw utility can be used to 39send an arbitrary SCSI command (supplied on the command line) to the 40given <I>DEVICE</I>. 41<P> 42 43sg_decode_sense can be used to decode SCSI sense data given on the command 44line or in a file. sg_raw -vvv will output the T10 name of a given SCSI 45CDB which is most often 16 bytes or less in length. 46<P> 47 48SCSI draft standards can be found at <A HREF="https://www.t10.org">https://www.t10.org</A> . The standards 49themselves can be purchased from ANSI and other standards organizations. 50A good overview of various SCSI standards can be seen in 51<A HREF="https://www.t10.org/scsi-3.htm">https://www.t10.org/scsi-3.htm</A> with the SCSI command sets in the upper part 52of the diagram. The highest level (i.e. most abstract) document is the SCSI 53Architecture Model (SAM) with SAM-5 being the most recent standard (ANSI 54INCITS 515-2016) with the most recent draft being SAM-6 revision 4 . SCSI 55commands in common with all device types can be found in SCSI Primary 56Commands (SPC) of which SPC-4 is the most recent standard (ANSI INCITS 57513-2015). The most recent SPC draft is SPC-5 revision 21. Block device 58specific commands (e.g. as used by disks) are in SBC, those for tape drives 59in SSC, those for SCSI enclosures in SES and those for CD/DVD/BD drives in 60MMC. 61<P> 62 63It is becoming more common to control ATA disks with the SCSI command set. 64This involves the translation of SCSI commands to their corresponding ATA 65equivalents (and that is an imperfect mapping in some cases). The relevant 66standard is called SCSI to ATA Translation (SAT, SAT-2 and SAT-3) are 67now standards at INCITS(ANSI) and ISO while SAT-4 is at the draft stage. 68The logic to perform the command translation is often called a SAT Layer or 69SATL and may be within an operating system, in host bus adapter firmware or 70in an external device (e.g. associated with a SAS expander). See 71<A HREF="https://www.t10.org">https://www.t10.org</A> for more information. 72<P> 73 74There is some support for SCSI tape devices but not for their basic 75operation. The reader is referred to the "mt" utility. 76<P> 77 78There are two generations of command line option usage. The newer 79utilities (written since July 2004) use the getopt_long() function to parse 80command line options. With that function, each option has two representations: 81a short form (e.g. '-v') and a longer form (e.g. '--verbose'). If an 82argument is required then it follows a space (optionally) in the short form 83and a "=" in the longer form (e.g. in the sg_verify utility '-l 2a6h' 84and '--lba=2a6h' are equivalent). Note that with getopt_long(), short form 85options can be elided, for example: '-all' is equivalent to '-a -l -l'. 86The <I>DEVICE</I> argument may appear after, between or prior to any options. 87<P> 88 89The older utilities, including as sg_inq, sg_logs, sg_modes, sg_opcode, 90sg_rbuff, sg_readcap, sg_senddiag, sg_start and sg_turs had individual 91command line processing code typically based on a single "-" followed by one 92or more characters. If an argument is needed then it follows a "=" ( 93e.g. '-p=1f' in sg_modes with its older interface). Various options can be 94elided as long as it is not ambiguous (e.g. '-vv' to increase the verbosity). 95<P> 96 97Over time the command line interface of these older utilities became messy 98and overloaded with options. So in sg3_utils version 1.23 the command line 99interface of these older utilities was altered to have both a cleaner 100getopt_long() interface and their older interface for backward compatibility. 101By default these older utilities use their getopt_long() based interface. 102The getopt_long() is a GNU extension (i.e. not yet POSIX certified) but 103more recent command line utilities tend to use it. That can be overridden 104by defining the SG3_UTILS_OLD_OPTS environment variable or using '-O' 105or '--old' as the first command line option. The man pages of the older 106utilities documents the details. 107<P> 108 109Several sg3_utils utilities are based on the Unix dd command (e.g. sg_dd) 110and permit copying data at the level of SCSI READ and WRITE commands. sg_dd 111is tightly bound to Linux and hence is not ported to other OSes. A more 112generic utility (than sg_dd) called ddpt in a package of the same name has 113been ported to other OSes. 114<A NAME="lbAE"> </A> 115<H2>ENVIRONMENT VARIABLES</H2> 116 117The SG3_UTILS_OLD_OPTS environment variable is explained in the previous 118section. It is only for backward compatibility of the command line options 119for older utilities. 120<P> 121 122The SG3_UTILS_DSENSE environment variable may be set to a number. It is 123only used by the embedded SNTL within the library used by the utilities in 124this library. SNTL is a SCSI to NVMe Translation Layer. This environment 125variable defaults to 0 which will lead to any utility that issues a SCSI 126command that is translated to a NVMe command (by the embedded SNTL) that 127fails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this 128variable is non-zero then then the returned SCSI sense will be in 'descriptor' 129format. 130<P> 131 132Several utilities have their own environment variable setting (e.g. 133sg_persist has SG_PERSIST_IN_RDONLY). See individual utility man pages 134for more information. 135<P> 136 137There is a Linux specific environment variable called SG3_UTILS_LINUX_NANO 138that if defined and the sg driver in the system is 4.0.30 or later, will 139show command durations in nanoseconds rather than the default milliseconds. 140Command durations are typically only shown if --verbose is used 3 or more 141times. Due to an interface problem (a 32 bit integer that should be 64 bits 142with the benefit of hindsight) the maximum duration that can be represented 143in nanoseconds is about 4.2 seconds. If longer durations may occur then 144don't define this environment variable (or undefine it). 145<A NAME="lbAF"> </A> 146<H2>LINUX DEVICE NAMING</H2> 147 148Most disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc, etc. 149SCSI disks in Linux have always had names like that but in recent Linux 150kernels it has become more common for many other disks (including SATA 151disks and USB storage devices) to be named like that. Partitions within a 152disk are specified by a number appended to the device name, starting at 1531 (e.g. /dev/sda1 ). 154<P> 155 156Tape drives are named /dev/st<num> or /dev/nst<num> where <num> starts 157at zero. Additionally one letter from this list: "lma" may be appended to 158the name. CD, DVD and BD readers (and writers) are named /dev/sr<num> 159where <num> start at zero. There are less used SCSI device type names, 160the dmesg and the lsscsi commands may help to find if any are attached to 161a running system. 162<P> 163 164There is also a SCSI device driver which offers alternate generic access 165to SCSI devices. It uses names of the form /dev/sg<num> where <num> starts 166at zero. The "lsscsi -g" command may be useful in finding these and which 167generic name corresponds to a device type name (e.g. /dev/sg2 may 168correspond to /dev/sda). In the lk 2.6 series a block SCSI generic 169driver was introduced and its names are of the form 170/dev/bsg/<h:c:t:l> where h, c, t and l are numbers. Again see the lsscsi 171command to find the correspondence between that SCSI tuple (i.e. <h:c:t:l>) 172and alternate device names. 173<P> 174 175Prior to the Linux kernel 2.6 series these utilities could only use 176generic device names (e.g. /dev/sg1 ). In almost all cases in the Linux 177kernel 2.6 series, any device name can be used by these utilities. 178<P> 179 180Very little has changed in Linux device naming in the Linux kernel 3 181and 4 series. 182<A NAME="lbAG"> </A> 183<H2>WINDOWS DEVICE NAMING</H2> 184 185Storage and related devices can have several device names in Windows. 186Probably the most common in the volume name (e.g. "D:"). There are also 187a "class" device names such as "PhysicalDrive<n>", "CDROM<n>" 188and "TAPE<n>". <n> is an integer starting at 0 allocated in ascending 189order as devices are discovered (and sometimes rediscovered). 190<P> 191 192Some storage devices have a SCSI lower level device name which starts 193with a SCSI (pseudo) adapter name of the form "SCSI<n>:". To this is added 194sub-addressing in the form of a "bus" number, a "target" identifier and 195a LUN (Logical Unit Number). The "bus" number is also known as a "PathId". 196These are assembled to form a device name of the 197form: "SCSI<n>:<bus>,<target>,<lun>". The trailing ",<lun>" may be omitted 198in which case a LUN of zero is assumed. This lower level device name cannot 199often be used directly since Windows blocks attempts to use it if a class 200driver has "claimed" the device. There are SCSI device types (e.g. 201Automation/Drive interface type) for which there is no class driver. At 202least two transports ("bus types" in Windows jargon): USB and IEEE 1394 do 203not have a "scsi" device names of this form. 204<P> 205 206In keeping with DOS file system conventions, the various device names 207can be given in upper, lower or mixed case. Since "PhysicalDrive<n>" is 208tedious to write, a shortened form of "PD<n>" is permitted by all 209utilities in this package. 210<P> 211 212A single device (e.g. a disk) can have many device names. For 213example: "PD0" can also be "C:", "D:" and "SCSI0:0,1,0". The two volume names 214reflect that the disk has two partitions on it. Disk partitions that are 215not recognized by Windows are not usually given a volume name. However 216Vista does show a volume name for a disk which has no partitions recognized 217by it and when selected invites the user to format it (which may be rather 218unfriendly to other OSes). 219<P> 220 221These utilities assume a given device name is in the Win32 device namespace. 222To make that explicit "\\.\" can be prepended to the device names mentioned 223in this section. Beware that backslash is an escape character in Unix like 224shells and the C programming language. In a shell like Msys (from MinGW) 225each backslash may need to be typed twice. 226<P> 227 228The sg_scan utility within this package lists out Windows device names in 229a form that is suitable for other utilities in this package to use. 230<A NAME="lbAH"> </A> 231<H2>FREEBSD DEVICE NAMING</H2> 232 233SCSI disks have block names of the form /dev/da<num> where <num> is an 234integer starting at zero. The "da" is replaced by "sa" for SCSI tape 235drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a 236corresponding pass-through device name of the form /dev/pass<num> 237where <num> is an integer starting at zero. The "camcontrol devlist" 238command may be useful for finding out which SCSI device names are 239available and the correspondence between class and pass-through names. 240<P> 241 242FreeBSD allows device names to be given without the leading "/dev/" (e.g. 243da0 instead of /dev/da0). That worked in this package up until version 2441.43 when the unadorned device name (e.g. "da0") gave an error. The 245original action (i.e. allowing unadorned device names) has been restored 246in version 1.46 . Also note that symlinks (to device names) are followed 247before prepending "/dev/" if the resultant name doesn't start with a "/". 248<P> 249 250FreeBSD's NVMe naming has been evolving. The controller naming is the 251same as Linux: "/dev/nvme<n>" but the namespaces have an 252extra "s" (e.g. "/dev/nvme0ns1"). The latter is not a block (GEOM) 253device (strictly speaking FreeBSD does not have block devices). Initially 254FreeBSD had "/dev/nvd<m>" GEOM devices that were not based on the CAM 255subsystem. Then in FreeBSD release 12 a new nda driver was added that is 256CAM (and GEOM) based for NVMe namespaces; it has names like "/dev/nda0". 257The preferred device nodes for this package are "/dev/nvme0" for NVMe 258controllers and "/dev/nda0" for NVMe namespaces. 259<A NAME="lbAI"> </A> 260<H2>SOLARIS DEVICE NAMING</H2> 261 262SCSI device names below the /dev directory have a form like: c5t4d3s2 263where the number following "c" is the controller (HBA) number, the number 264following "t" is the target number (from the SCSI parallel interface days) 265and the number following "d" is the LUN. Following the "s" is the slice 266number which is related to a partition and by convention "s2" is the whole 267disk. 268<P> 269 270OpenSolaris also has a c5t4d3p2 form where the number following the "p" is 271the partition number apart from "p0" which is the whole disk. So a whole 272disk may be referred to as either c5t4d3, c5t4d3s2 or c5t4d3p0 . 273<P> 274 275And these device names are duplicated in the /dev/dsk and /dev/rdsk 276directories. The former is the block device name and the latter is 277for "raw" (or char device) access which is what sg3_utils needs. So in 278OpenSolaris something of the form 'sg_inq /dev/rdsk/c5t4d3p0' should work. 279If it doesn't work then add a '-vvv' option for more debug information. 280Trying this form 'sg_inq /dev/dsk/c5t4d3p0' (note "rdsk" changed to "dsk") 281will result in an "inappropriate ioctl for device" error. 282<P> 283 284The device names within the /dev directory are typically symbolic links to 285much longer topological names in the /device directory. In Solaris cd/dvd/bd 286drives seem to be treated as disks and so are found in the /dev/rdsk 287directory. Tape drives appear in the /dev/rmt directory. 288<P> 289 290There is also a sgen (SCSI generic) driver which by default does not attach 291to any device. See the /kernel/drv/sgen.conf file to control what is 292attached. Any attached device will have a device name of the 293form /dev/scsi/c5t4d3 . 294<P> 295 296Listing available SCSI devices in Solaris seems to be a challenge. "Use 297the 'format' command" advice works but seems a very dangerous way to list 298devices. [It does prompt again before doing any damage.] 'devfsadm -Cv' 299cleans out the clutter in the /dev/rdsk directory, only leaving what 300is "live". The "cfgadm -v" command looks promising. 301<A NAME="lbAJ"> </A> 302<H2>NVME SUPPORT</H2> 303 304NVMe (or NVM Express) is a relatively new storage transport and command 305set. The level of abstraction of the NVMe command set is somewhat lower 306the SCSI command sets, closer to the level of abstraction of ATA (and SATA) 307command sets. NVMe claims to be designed with flash and modern "solid 308state" storage in mind, something unheard of when SCSI was originally 309developed in the 1980s. 310<P> 311 312The SCSI command sets' advantage is the length of time they have been in 313place and the existing tools (like these) to support it. Plus SCSI command 314sets level of abstraction is both and advantage and disadvantage. Recently 315the NVME-MI (Management Interface) designers decide to use the SCSI 316Enclosure Services (SES-3) standard "as is" with the addition of two 317tunnelling NVME-MI commands: SES Send and SES Receive. This means after the 318OS interface differences are taken into account, the sg_ses, sg_ses_microcode 319and sg_senddiag utilities can be used on a NVMe device that supports a newer 320version of NVME-MI. 321<P> 322 323The NVME-MI SES Send and SES Receive commands correspond to the SCSI 324SEND DIAGNOSTIC and RECEIVE DIAGNOSTIC RESULTS commands respectively. 325There are however a few other commands that need to be translated, the 326most important of which is the SCSI INQUIRY command to the NVMe Identify 327controller/namespace. Starting in version 1.43 these utilities contain a 328small SNTL (SCSI to NVMe Translation Layer) to take care of these details. 329<P> 330 331As a side effect of this "juggling" if the sg_inq utility is used (without 332the --page= option) on a NVMe <I>DEVICE</I> then the actual NVMe 333Identifier (controller and possibly namespace) responses are decoded and 334output. However if 'sg_inq --page=sinq <device>' is given for the 335same <I>DEVICE</I> then parts of the NVMe Identify controller and namespace 336response are translated to a SCSI standard INQUIRY response which is then 337decoded and output. 338<P> 339 340Apart from the special case with the sg_inq, all other utilities in the 341package assume they are talking to a SCSI device and decode any response 342accordingly. One easy way for users to see the underlying device is a 343NVMe device is the standard INQUIRY response Vendor Identification field 344of "NVMe " (an 8 character long string with 4 spaces to the right). 345<P> 346 347The following SCSI commands are currently supported by the SNTL library: 348INQUIRY, MODE SELECT(10), MODE SENSE(10), READ(10,16), READ CAPACITY(10,16), 349RECEIVE DIAGNOSTIC RESULTS, REQUEST SENSE, REPORT LUNS, REPORT SUPPORTED 350OPERATION CODES, REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS, SEND 351DIAGNOSTICS, START STOP UNIT, SYNCHRONIZE CACHE(10,16), TEST UNIT READY, 352VERIFY(10,16), WRITE(10,16) and WRITE SAME(10,16). 353<A NAME="lbAK"> </A> 354<H2>EXIT STATUS</H2> 355 356To aid scripts that call these utilities, the exit status is set to indicate 357success (0) or failure (1 or more). Note that some of the lower values 358correspond to the SCSI sense key values. 359<P> 360 361The exit status values listed below can be given to the sg_decode_sense 362utility (which is found in this package) as follows: 363<BR> 364 365<BR> sg_decode_sense --err=<exit_status> 366<BR> 367 368and a short explanatory string will be output to stdout. 369<P> 370 371The exit status values are: 372<DL COMPACT> 373<DT><B>0</B> 374 375<DD> 376success. Also used for some utilities that wish to return a boolean value 377for the "true" case (and that no error has occurred). The false case is 378conveyed by exit status 36. 379<DT><B>1</B> 380 381<DD> 382syntax error. Either illegal command line options, options with bad 383arguments or a combination of options that is not permitted. 384<DT><B>2</B> 385 386<DD> 387the <I>DEVICE</I> reports that it is not ready for the operation requested. 388The <I>DEVICE</I> may be in the process of becoming ready (e.g. spinning up 389but not at speed) so the utility may work after a wait. In Linux the 390<I>DEVICE</I> may be temporarily blocked while error recovery is taking place. 391<DT><B>3</B> 392 393<DD> 394the <I>DEVICE</I> reports a medium or hardware error (or a blank check). For 395example an attempt to read a corrupted block on a disk will yield this value. 396<DT><B>5</B> 397 398<DD> 399the <I>DEVICE</I> reports an "illegal request" with an additional sense code 400other than "invalid command operation code". This is often a supported 401command with a field set requesting an unsupported capability. For commands 402that require a "service action" field this value can indicate that the 403command with that service action value is not supported. 404<DT><B>6</B> 405 406<DD> 407the <I>DEVICE</I> reports a "unit attention" condition. This usually indicates 408that something unrelated to the requested command has occurred (e.g. a device 409reset) potentially before the current SCSI command was sent. The requested 410command has not been executed by the device. Note that unit attention 411conditions are usually only reported once by a device. 412<DT><B>7</B> 413 414<DD> 415the <I>DEVICE</I> reports a "data protect" sense key. This implies some 416mechanism has blocked writes (or possibly all access to the media). 417<DT><B>9</B> 418 419<DD> 420the <I>DEVICE</I> reports an illegal request with an additional sense code 421of "invalid command operation code" which means that it doesn't support the 422requested command. 423<DT><B>10</B> 424 425<DD> 426the <I>DEVICE</I> reports a "copy aborted". This implies another command or 427device problem has stopped a copy operation. The EXTENDED COPY family of 428commands (including WRITE USING TOKEN) may return this sense key. 429<DT><B>11</B> 430 431<DD> 432the <I>DEVICE</I> reports an aborted command. In some cases aborted 433commands can be retried immediately (e.g. if the transport aborted 434the command due to congestion). 435<DT><B>14</B> 436 437<DD> 438the <I>DEVICE</I> reports a miscompare sense key. VERIFY and COMPARE AND 439WRITE commands may report this. 440<DT><B>15</B> 441 442<DD> 443the utility is unable to open, close or use the given <I>DEVICE</I> or some 444other file. The given file name could be incorrect or there may be 445permission problems. Adding the '-v' option may give more information. 446<DT><B>17</B> 447 448<DD> 449a SCSI "Illegal request" sense code received with a flag indicating the 450Info field is valid. This is often a LBA but its meaning is command specific. 451<DT><B>18</B> 452 453<DD> 454the <I>DEVICE</I> reports a medium or hardware error (or a blank check) 455with a flag indicating the Info field is valid. This is often a LBA (of 456the first encountered error) but its meaning is command specific. 457<DT><B>20</B> 458 459<DD> 460the <I>DEVICE</I> reports it has a check condition but "no sense" 461and non-zero information in its additional sense codes. Some polling 462commands (e.g. REQUEST SENSE) can receive this response. There may 463be useful information in the sense data such as a progress indication. 464<DT><B>21</B> 465 466<DD> 467the <I>DEVICE</I> reports a "recovered error". The requested command 468was successful. Most likely a utility will report a recovered error 469to stderr and continue, probably leaving the utility with an exit 470status of 0 . 471<DT><B>22</B> 472 473<DD> 474the <I>DEVICE</I> reports that the current command or its parameters imply 475a logical block address (LBA) that is out of range. This happens surprisingly 476often when trying to access the last block on a storage device; either a 477classic "off by one" logic error or a misreading of the response from READ 478CAPACITY(10 or 16) in which the address of the last block rather than the 479number of blocks on the <I>DEVICE</I> is returned. Since LBAs are origin zero 480they range from 0 to n-1 where n is the number of blocks on the <I>DEVICE</I>, 481so the LBA of the last block is one less than the total number of blocks. 482<DT><B>24</B> 483 484<DD> 485the <I>DEVICE</I> reports a SCSI status of "reservation conflict". This 486means access to the <I>DEVICE</I> with the current command has been blocked 487because another machine (HBA or SCSI "initiator") holds a reservation on 488this <I>DEVICE</I>. On modern SCSI systems this is related to the use of 489the PERSISTENT RESERVATION family of commands. 490<DT><B>25</B> 491 492<DD> 493the <I>DEVICE</I> reports a SCSI status of "condition met". Currently only 494the PRE-FETCH command (see SBC-4) yields this status. 495<DT><B>26</B> 496 497<DD> 498the <I>DEVICE</I> reports a SCSI status of "busy". SAM-6 defines this status 499as the logical unit is temporarily unable to process a command. It is 500recommended to re-issue the command. 501<DT><B>27</B> 502 503<DD> 504the <I>DEVICE</I> reports a SCSI status of "task set full". 505<DT><B>28</B> 506 507<DD> 508the <I>DEVICE</I> reports a SCSI status of "ACA active". ACA is "auto 509contingent allegiance" and is seldom used. 510<DT><B>29</B> 511 512<DD> 513the <I>DEVICE</I> reports a SCSI status of "task aborted". SAM-5 says: 514"This status shall be returned if a command is aborted by a command or task 515management function on another I_T nexus and the Control mode page TAS bit 516is set to one". 517<DT><B>31</B> 518 519<DD> 520error involving two or more command line options. They may be contradicting, 521select an unsupported mode, or a required option (given the context) is 522missing. 523<DT><B>32</B> 524 525<DD> 526there is a logic error in the utility. It corresponds to code comments 527like "shouldn't/can't get here". Perhaps the author should be informed. 528<DT><B>33</B> 529 530<DD> 531the command sent to <I>DEVICE</I> has timed out. 532<DT><B>34</B> 533 534<DD> 535this is a Windows only exit status and indicates that the Windows error 536number (32 bits) cannot meaningfully be mapped to an equivalent Unix error 537number returned as the exit status (7 bits). 538<DT><B>35</B> 539 540<DD> 541a transport error has occurred. This will either be in the driver (e.g. HBA 542driver) or in the interconnect between the host (initiator) and the 543device (target). For example in SAS an expander can run out of paths and 544thus be unable to return the user data for a READ command. 545<DT><B>36</B> 546 547<DD> 548no error has occurred plus the utility wants to convey a boolean value 549of false. The corresponding true value is conveyed by a 0 exit status. 550<DT><B>40</B> 551 552<DD> 553the command sent to <I>DEVICE</I> has received an "aborted command" sense 554key with an additional sense code of 0x10. This value is related to 555problems with protection information (PI or DIF). For example this error 556may occur when reading a block on a drive that has never been written (or 557is unmapped) if that drive was formatted with type 1, 2 or 3 protection. 558<DT><B>41</B> 559 560<DD> 561the command sent to <I>DEVICE</I> has received an "aborted command" sense 562key with an additional sense code of 0x10 (as with error code) plus a flag 563indicating the Info field is valid. 564<DT><B>48</B> 565 566<DD> 567this is an internal message indicating a NVMe status field (SF) is other 568than zero after a command has been executed (i.e. something went wrong). 569Work in this area is currently experimental. 570<DT><B>49</B> 571 572<DD> 573low level driver reports a response's residual count (i.e. number of bytes 574actually received by HBA is 'requested_bytes - residual_count') that is 575nonsensical. 576<DT><B>50</B> 577 578<DD> 579OS system calls that fail often return a small integer number to help. In 580Unix these are called "errno" values where 0 implies no error. These error 581codes set aside 51 to 96 for mapping these errno values but that may not be 582sufficient. Higher errno values that cannot be mapped are all mapped to 583this value (i.e. 50). 584<BR> 585 586Note that an errno value of 0 is mapped to error code 0. 587<DT><B>50 + <os_error_number></B> 588 589<DD> 590OS system calls that fail often return a small integer number to help 591indicate what the error is. For example in Unix the inability of a system 592call to allocate memory returns (in 'errno') ENOMEM which often is 593associated with the integer 12. So 62 (i.e. '50 + 12') may be returned 594by a utility in this case. It is also possible that a utility in this 595package reports 50+ENOMEM when it can't allocate memory, not necessarily 596from an OS system call. In recent versions of Linux the file showing the 597mapping between symbolic constants (e.g. ENOMEM) and the corresponding 598integer is in the kernel source code file: 599include/uapi/asm-generic/errno-base.h 600<BR> 601 602Note that errno values that are greater than or equal to 47 cannot fit in 603range provided. Instead they are all mapped to 50 as discussed in the 604previous entry. 605<DT><B>97</B> 606 607<DD> 608a SCSI command response failed sanity checks. 609<DT><B>98</B> 610 611<DD> 612the <I>DEVICE</I> reports it has a check condition but the error 613doesn't fit into any of the above categories. 614<DT><B>99</B> 615 616<DD> 617any errors that can't be categorized into values 1 to 98 may yield 618this value. This includes transport and operating system errors 619after the command has been sent to the device. 620<DT><B>100-125</B> 621 622<DD> 623these error codes are used by the ddpt utility which uses the sg3_utils 624library. They are mainly specialized error codes associated with offloaded 625copies. 626<DT><B>126</B> 627 628<DD> 629the utility was found but could not be executed. That might occur if the 630executable does not have execute permissions. 631<DT><B>127</B> 632 633<DD> 634This is the exit status for utility not found. That might occur when a 635script calls a utility in this package but the PATH environment variable 636has not been properly set up, so the script cannot find the executable. 637<DT><B>128 + <signum></B> 638 639<DD> 640If a signal kills a utility then the exit status is 128 plus the signal 641number. For example if a segmentation fault occurs then a utility is 642typically killed by SIGSEGV which according to 'man 7 signal' has an 643associated signal number of 11; so the exit status will be 139 . 644<DT><B>255</B> 645 646<DD> 647the utility tried to yield an exit status of 255 or larger. That should 648not happen; given here for completeness. 649</DL> 650<P> 651 652Most of the error conditions reported above will be repeatable (an example 653of one that is not is "unit attention") so the utility can be run again with 654the '-v' option (or several) to obtain more information. 655<A NAME="lbAL"> </A> 656<H2>COMMON OPTIONS</H2> 657 658Arguments to long options are mandatory for short options as well. In the 659short form an argument to an option uses zero or more spaces as a 660separator (i.e. the short form does not use "=" as a separator). 661<P> 662 663If an option takes a numeric argument then that argument is assumed to 664be decimal unless otherwise indicated (e.g. with a leading "0x", a 665trailing "h" or as noted in the usage message). 666<P> 667 668Some options are used uniformly in most of the utilities in this 669package. Those options are listed below. Note that there are some 670exceptions. 671<DL COMPACT> 672<DT><B>-d</B>, <B>--dry-run</B><DD> 673utilities that can cause lots of user data to be lost or overwritten 674sometimes have a <I>--dry-run</I> option. Device modifying actions are 675typically bypassed (or skipped) to implement a policy of "do no harm". 676This allows complex command line invocations to be tested before the 677action required (e.g. format a disk) is performed. The <I>--dry-run</I> 678option has become a common feature of many command line utilities (e.g. 679the Unix 'patch' command), not just those from this package. 680<BR> 681 682Note that most hyphenated option names in this package also can be given 683with an underscore rather than a hyphen (e.g. <I>--dry_run</I>). 684<DT><B>-e</B>, <B>--enumerate</B><DD> 685some utilities (e.g. sg_ses and sg_vpd) store a lot of information in 686internal tables. This option will output that information in some readable 687form (e.g. sorted by an acronym or by page number) then exit. Note that 688with this option <I>DEVICE</I> is ignored (as are most other options) and no 689SCSI IO takes place, so the invoker does not need any elevated permissions. 690<DT><B>-h</B>, <B>-?</B>, <B>--help</B><DD> 691output the usage message then exit. In a few older utilities the '-h' 692option requests hexadecimal output. In these cases the '-?' option will 693output the usage message then exit. 694<DT><B>-H</B>, <B>--hex</B><DD> 695for SCSI commands that yield a non-trivial response, print out that 696response in ASCII hexadecimal. To produce hexadecimal that can be parsed 697by other utilities (e.g. without a relative address to the left and without 698trailing ASCII) use this option three or four times. 699<DT><B>-i</B>, <B>--in</B>=<I>FN</I><DD> 700many SCSI commands fetch a significant amount of data (returned in the 701data-in buffer) which several of these utilities decode (e.g. sg_vpd and 702sg_logs). To separate the two steps of fetching the data from a SCSI device 703and then decoding it, this option has been added. The first step (fetching 704the data) can be done using the <I>--hex</I> or <I>--raw</I> option and 705redirecting the command line output to a file (often done with ">" in Unix 706based operating systems). The difference between <I>--hex</I> and 707<I>--raw</I> is that the former produces output in ASCII hexadecimal 708while <I>--raw</I> produces its output in "raw" binary. 709<BR> 710 711The second step (i.e. decoding the SCSI response data now held in a file) 712can be done using this <I>--in=FN</I> option where the file name is 713<I>FN</I>. If "-" is used for <I>FN</I> then stdin is assumed, again this 714allows for command line redirection (or piping). That file (or stdin) 715is assumed to contain ASCII hexadecimal unless the <I>--raw</I> option is 716also given in which case it is assumed to be binary. Notice that the meaning 717of the <I>--raw</I> option is "flipped" when used with <I>--in=FN</I> to 718act on the input, typically it acts on the output data. 719<BR> 720 721Since the structure of the data returned by SCSI commands varies 722considerably then the usage information or the manpage of the utility being 723used should be checked. In some cases <I>--hex</I> may need to be used 724multiple times (and is more conveniently given as '-HH' or '-HHH). 725<DT><B>-i</B>, <B>--inhex</B>=<I>FN</I><DD> 726This option has the same or similar functionality as <I>--in=FN</I>. And 727perhaps 'inhex' is more descriptive since by default, ASCII hexadecimal is 728expected in the contents of file: <I>FN</I>. Alternatively the short form 729option may be <I>-I</I> or <I>-X</I>. See the "FORMAT OF FILES CONTAINING 730ASCII HEX" section below for more information. 731<DT><B>-m</B>, <B>--maxlen</B>=<I>LEN</I><DD> 732several important SCSI commands (e.g. INQUIRY and MODE SENSE) have response 733lengths that vary depending on many factors, only some of which these 734utilities take into account. The maximum response length is typically 735specified in the 'allocation length' field of the cdb. In the absence of 736this option, several utilities use a default allocation length (sometimes 737recommended in the SCSI draft standards) or a "double fetch" strategy. 738See <A HREF="../man8/sg_logs.8.html">sg_logs</A>(8) for its description of a "double fetch" strategy. These 739techniques are imperfect and in the presence of faulty SCSI targets can 740cause problems (e.g. some USB mass storage devices freeze if they receive 741an INQUIRY allocation length other than 36). Also use of this option 742disables any "double fetch" strategy that may have otherwise been used. 743<BR> 744 745To head off a class of degenerate bugs, if <I>LEN</I> is less than 16 then 746it is ignored (usually with a warning message) and the default value is 747used instead. Some utilities use 4 (bytes), rather than 16, as the cutoff 748value. 749<DT><B>-r</B>, <B>--raw</B><DD> 750for SCSI commands that yield a non-trivial response, output that response 751in binary to stdout. If any error messages or warning are produced they are 752usually sent to stderr so as to not interfere with the output from this 753option. 754<BR> 755 756Some utilities that consume data to send to the <I>DEVICE</I> along with the 757SCSI command, use this option. Alternatively the <I>--in=FN</I> option causes 758<I>DEVICE</I> to be ignored and the response data (to be decoded) fetched 759from a file named <I>FN</I>. In these cases this option may indicate that 760binary data can be read from stdin or from a nominated file (e.g. <I>FN</I>). 761<DT><B>-t</B>, <B>--timeout</B>=<I>SECS</I><DD> 762utilities that issue potentially long-running SCSI commands often have a 763<I>--timeout=SECS</I> option. This typically instructs the operating system 764to abort the SCSI command in question once the timeout expires. Aborting 765SCSI commands is typically a messy business and in the case of format like 766commands may leave the device in a "format corrupt" state requiring another 767long-running re-initialization command to be sent. The argument, <I>SECS</I>, 768is usually in seconds and the short form of the option may be something 769other than <I>-t</I> since the timeout option was typically added later as 770storage devices grew in size and initialization commands took longer. Since 771many utilities had relatively long internal command timeouts before this 772option was introduced, the actual command timeout given to the operating 773systems is the higher of the internal timeout and <I>SECS</I>. 774<BR> 775 776Many long running SCSI commands have an IMMED bit which causes the command 777to finish relatively quickly but the initialization process to continue. In 778such cases the REQUEST SENSE command can be used to monitor progress with 779its progress indication field (see the sg_requests and sg_turs utilities). 780Utilities that send such SCSI command either have an <I>--immed</I> option 781or a <I>--wait</I> option which is the logical inverse of the "immediate" 782action. 783<DT><B>-v</B>, <B>--verbose</B><DD> 784increase the level of verbosity, (i.e. debug output). Can be used multiple 785times to further increase verbosity. The additional output caused by this 786option is almost always sent to stderr. 787<DT><B>-V</B>, <B>--version</B><DD> 788print the version string and then exit. Each utility has its own version 789number and date of last code change. 790</DL> 791<A NAME="lbAM"> </A> 792<H2>NUMERIC ARGUMENTS</H2> 793 794Many utilities have command line options that take numeric arguments. These 795numeric arguments can be large values (e.g. a logical block address (LBA) on 796a disk) and can be inconvenient to enter in the default decimal 797representation. So various other representations are permitted. 798<P> 799 800Multiplicative suffixes are accepted. They are one, two or three letter 801strings appended directly after the number to which they apply: 802<P> 803 804<BR> c C *1 805<BR> 806 807<BR> w W *2 808<BR> 809 810<BR> b B *512 811<BR> 812 813<BR> k K KiB *1024 814<BR> 815 816<BR> KB kB *1000 817<BR> 818 819<BR> m M MiB *1048576 820<BR> 821 822<BR> MB mB *1000000 823<BR> 824 825<BR> g G GiB *(2^30) 826<BR> 827 828<BR> GB gB *(10^9) 829<BR> 830 831<BR> t T TiB *(2^40) 832<BR> 833 834<BR> TB *(10^12) 835<BR> 836 837<BR> p P PiB *(2^50) 838<BR> 839 840<BR> PB *(10^15) 841<P> 842 843An example is "2k" for 2048. The large tera and peta suffixes are only 844available for numeric arguments that might require 64 bits to represent 845internally. 846<P> 847 848These multiplicative suffixes are compatible with GNU's dd command (since 8492002) which claims compliance with SI and with IEC 60027-2. 850<P> 851 852A suffix of the form "x<n>" multiplies the preceding number by <n>. An 853example is "2x33" for "66". The left argument cannot be '0' as '0x' will 854be interpreted as hexadecimal number prefix (see below). The left 855argument to the multiplication must end in a hexadecimal digit (i.e. 8560 to f) and the whole expression cannot have any embedded whitespace (e.g. 857spaces). An ugly example: "0xfx0x2" for 30. 858<P> 859 860A suffix of the form "+<n>" adds the preceding number to <n>. An example 861is "3+1k" for "1027". The left argument to the addition must end in a 862hexadecimal digit (i.e. 0 to f) and the whole expression cannot have any 863embedded whitespace (e.g. spaces). Another example: "0xf+0x2" for 17. 864<P> 865 866Alternatively numerical arguments can be given in hexadecimal. There are 867two syntaxes. The number can be preceded by either "0x" or "0X" as found 868in the C programming language. The second hexadecimal representation is a 869trailing "h" or "H" as found in (storage) standards. When hex numbers are 870given, multipliers cannot be used. For example the decimal value "256" can 871be given as "0x100" or "100h". 872<A NAME="lbAN"> </A> 873<H2>FORMAT OF FILES CONTAINING ASCII HEX</H2> 874 875Such a file is assumed to contain a sequence of one or two digit ASCII 876hexadecimal values separated by whitespace. "Whitespace consists of either 877spaces, tabs, blank lines, or any combination thereof". Each one or two digit 878ASCII hex pair is decoded into a byte (i.e. 8 bits). The following will be 879decoded to valid (ascending valued) 880bytes: '0', '01', '3', 'c', 'F', '4a', 'cC', 'ff'. 881Lines containing only whitespace are ignored. The contents of any line 882containing a hash mark ('#') is ignored from that point until the end of that 883line. Users are encouraged to use hash marks to introduce comments in hex 884files. The author uses the extension'.hex' on such files. Examples can be 885found in the 'inhex' directory. 886<A NAME="lbAO"> </A> 887<H2>MICROCODE AND FIRMWARE</H2> 888 889There are two standardized methods for downloading microcode (i.e. device 890firmware) to a SCSI device. The more general way is with the SCSI WRITE 891BUFFER command, see the sg_write_buffer utility. SCSI enclosures have 892their own method based on the Download microcode control/status diagnostic 893page, see the sg_ses_microcode utility. 894<A NAME="lbAP"> </A> 895<H2>SCRIPTS, EXAMPLES and UTILS</H2> 896 897There are several bash shell scripts in the 'scripts' subdirectory that 898invoke compiled utilities (e.g. sg_readcap). Several of the scripts start 899with 'scsi_' rather than 'sg_'. One purpose of these scripts is to call the 900same utility (e.g. sg_readcap) on multiple devices. Most of the basic 901compiled utilities only allow one device as an argument. Some distributions 902install these scripts in a more visible directory (e.g. /usr/bin). Some of 903these scripts have man page entries. See the README file in the 'scripts' 904subdirectory. 905<P> 906 907There is some example C code plus examples of complex invocations in 908the 'examples' subdirectory. There is also a README file. The example C 909may be a simpler example of how to use a SCSI pass-through in Linux 910than the main utilities (found in the 'src' subdirectory). This is due 911to the fewer abstraction layers (e.g. they don't worry the MinGW in 912Windows may open a file in text rather than binary mode). 913<P> 914 915Some utilities that the author has found useful have been placed in 916the 'utils' subdirectory. 917<A NAME="lbAQ"> </A> 918<H2>WEB SITE</H2> 919 920There is a web page discussing this package at 921<A HREF="https://sg.danny.cz/sg/sg3_utils.html">https://sg.danny.cz/sg/sg3_utils.html</A> . The device naming used by this 922package on various operating systems is discussed at: 923<A HREF="https://sg.danny.cz/sg/device_name.html">https://sg.danny.cz/sg/device_name.html</A> . There is a git code mirror at 924<A HREF="https://github.com/hreinecke/sg3_utils">https://github.com/hreinecke/sg3_utils</A> . The principle code repository 925uses subversion and is on the author's equipment. The author keeps track 926of this via the subversion revision number which is an ascending integer 927(currently at 774 for this package). The github mirror gets updated 928periodically from the author's repository. Depending on the time of 929update, the above Downloads section at sg.danny.cz may be more up to 930date than the github mirror. 931<A NAME="lbAR"> </A> 932<H2>AUTHORS</H2> 933 934Written by Douglas Gilbert. Some utilities have been contributed, see the 935CREDITS file and individual source files (in the 'src' directory). 936<A NAME="lbAS"> </A> 937<H2>REPORTING BUGS</H2> 938 939Report bugs to <dgilbert at interlog dot com>. 940<A NAME="lbAT"> </A> 941<H2>COPYRIGHT</H2> 942 943Copyright © 1999-2021 Douglas Gilbert 944<BR> 945 946Some utilities are distributed under a GPL version 2 license while 947others, usually more recent ones, are under a FreeBSD license. The files 948that are common to almost all utilities and thus contain the most reusable 949code, namely sg_lib.[hc], sg_cmds_basic.[hc] and sg_cmds_extra.[hc] are 950under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY 951or FITNESS FOR A PARTICULAR PURPOSE. 952<A NAME="lbAU"> </A> 953<H2>SEE ALSO</H2> 954 955<B>sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), <A HREF="../man1/dmesg.1.html">dmesg</A>(1), <A HREF="../man1/mt.1.html">mt</A>(1)</B> 956 957<P> 958 959<HR> 960<A NAME="index"> </A><H2>Index</H2> 961<DL> 962<DT><A HREF="#lbAB">NAME</A><DD> 963<DT><A HREF="#lbAC">SYNOPSIS</A><DD> 964<DT><A HREF="#lbAD">DESCRIPTION</A><DD> 965<DT><A HREF="#lbAE">ENVIRONMENT VARIABLES</A><DD> 966<DT><A HREF="#lbAF">LINUX DEVICE NAMING</A><DD> 967<DT><A HREF="#lbAG">WINDOWS DEVICE NAMING</A><DD> 968<DT><A HREF="#lbAH">FREEBSD DEVICE NAMING</A><DD> 969<DT><A HREF="#lbAI">SOLARIS DEVICE NAMING</A><DD> 970<DT><A HREF="#lbAJ">NVME SUPPORT</A><DD> 971<DT><A HREF="#lbAK">EXIT STATUS</A><DD> 972<DT><A HREF="#lbAL">COMMON OPTIONS</A><DD> 973<DT><A HREF="#lbAM">NUMERIC ARGUMENTS</A><DD> 974<DT><A HREF="#lbAN">FORMAT OF FILES CONTAINING ASCII HEX</A><DD> 975<DT><A HREF="#lbAO">MICROCODE AND FIRMWARE</A><DD> 976<DT><A HREF="#lbAP">SCRIPTS, EXAMPLES and UTILS</A><DD> 977<DT><A HREF="#lbAQ">WEB SITE</A><DD> 978<DT><A HREF="#lbAR">AUTHORS</A><DD> 979<DT><A HREF="#lbAS">REPORTING BUGS</A><DD> 980<DT><A HREF="#lbAT">COPYRIGHT</A><DD> 981<DT><A HREF="#lbAU">SEE ALSO</A><DD> 982</DL> 983<HR> 984This document was created by 985<A HREF="/cgi-bin/man/man2html">man2html</A>, 986using the manual pages.<BR> 987Time: 03:12:28 GMT, November 11, 2021 988</BODY> 989</HTML> 990