diff options
Diffstat (limited to 'sg3_utils.man8.html')
| -rw-r--r-- | sg3_utils.man8.html | 989 |
1 files changed, 989 insertions, 0 deletions
diff --git a/sg3_utils.man8.html b/sg3_utils.man8.html new file mode 100644 index 00000000..579985d8 --- /dev/null +++ b/sg3_utils.man8.html @@ -0,0 +1,989 @@ +Content-type: text/html; charset=UTF-8 + +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<HTML><HEAD><TITLE>Man page of SG3_UTILS</TITLE> +</HEAD><BODY> +<H1>SG3_UTILS</H1> +Section: SG3_UTILS (8)<BR>Updated: November 2021<BR><A HREF="#index">Index</A> +<A HREF="../index.html">Return to Main Contents</A><HR> + +<A NAME="lbAB"> </A> +<H2>NAME</H2> + +sg3_utils - a package of utilities for sending SCSI commands +<A NAME="lbAC"> </A> +<H2>SYNOPSIS</H2> + +<B>sg_*</B> + +[<I>--dry-run</I>] [<I>--enumerate</I>] [<I>--help</I>] [<I>--hex</I>] +[<I>--in=FN</I>] [<I>--inhex=FN</I>] [<I>--maxlen=LEN</I>] [<I>--raw</I>] +[<I>--timeout=SECS</I>] [<I>--verbose</I>] [<I>--version</I>] +[<I>OTHER_OPTIONS</I>] <I>DEVICE</I> +<A NAME="lbAD"> </A> +<H2>DESCRIPTION</H2> + + +<P> + +sg3_utils is a package of utilities that send SCSI commands to the given +<I>DEVICE</I> via a SCSI pass through interface provided by the host +operating system. +<P> + +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 <I>DEVICE</I>. +<P> + +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. +<P> + +SCSI draft standards can be found at <A HREF="https://www.t10.org">https://www.t10.org</A> . The standards +themselves can be purchased from ANSI and other standards organizations. +A good overview of various SCSI standards can be seen in +<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 +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 21. 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. +<P> + +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 +<A HREF="https://www.t10.org">https://www.t10.org</A> for more information. +<P> + +There is some support for SCSI tape devices but not for their basic +operation. The reader is referred to the "mt" utility. +<P> + +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 <I>DEVICE</I> argument may appear after, between or prior to any options. +<P> + +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). +<P> + +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. +<P> + +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. +<A NAME="lbAE"> </A> +<H2>ENVIRONMENT VARIABLES</H2> + +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. +<P> + +The SG3_UTILS_DSENSE environment variable may be set to a number. It is +only used by the embedded SNTL within the library used by the utilities in +this library. SNTL is a SCSI to NVMe Translation Layer. This environment +variable defaults to 0 which will lead to any utility that issues a SCSI +command that is translated to a NVMe command (by the embedded SNTL) that +fails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this +variable is non-zero then then the returned SCSI sense will be in 'descriptor' +format. +<P> + +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. +<P> + +There is a Linux specific environment variable called SG3_UTILS_LINUX_NANO +that if defined and the sg driver in the system is 4.0.30 or later, will +show command durations in nanoseconds rather than the default milliseconds. +Command durations are typically only shown if --verbose is used 3 or more +times. Due to an interface problem (a 32 bit integer that should be 64 bits +with the benefit of hindsight) the maximum duration that can be represented +in nanoseconds is about 4.2 seconds. If longer durations may occur then +don't define this environment variable (or undefine it). +<A NAME="lbAF"> </A> +<H2>LINUX DEVICE NAMING</H2> + +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 ). +<P> + +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. +<P> + +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. +<P> + +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. +<P> + +Very little has changed in Linux device naming in the Linux kernel 3 +and 4 series. +<A NAME="lbAG"> </A> +<H2>WINDOWS DEVICE NAMING</H2> + +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). +<P> + +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. +<P> + +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. +<P> + +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). +<P> + +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. +<P> + +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. +<A NAME="lbAH"> </A> +<H2>FREEBSD DEVICE NAMING</H2> + +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. +<P> + +FreeBSD allows device names to be given without the leading "/dev/" (e.g. +da0 instead of /dev/da0). That worked in this package up until version +1.43 when the unadorned device name (e.g. "da0") gave an error. The +original action (i.e. allowing unadorned device names) has been restored +in version 1.46 . Also note that symlinks (to device names) are followed +before prepending "/dev/" if the resultant name doesn't start with a "/". +<P> + +FreeBSD's NVMe naming has been evolving. The controller naming is the +same as Linux: "/dev/nvme<n>" but the namespaces have an +extra "s" (e.g. "/dev/nvme0ns1"). The latter is not a block (GEOM) +device (strictly speaking FreeBSD does not have block devices). Initially +FreeBSD had "/dev/nvd<m>" GEOM devices that were not based on the CAM +subsystem. Then in FreeBSD release 12 a new nda driver was added that is +CAM (and GEOM) based for NVMe namespaces; it has names like "/dev/nda0". +The preferred device nodes for this package are "/dev/nvme0" for NVMe +controllers and "/dev/nda0" for NVMe namespaces. +<A NAME="lbAI"> </A> +<H2>SOLARIS DEVICE NAMING</H2> + +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. +<P> + +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 . +<P> + +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. +<P> + +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. +<P> + +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 . +<P> + +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. +<A NAME="lbAJ"> </A> +<H2>NVME SUPPORT</H2> + +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. +<P> + +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. +<P> + +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. Starting in version 1.43 these utilities contain a +small SNTL (SCSI to NVMe Translation Layer) to take care of these details. +<P> + +As a side effect of this "juggling" if the sg_inq utility is used (without +the --page= option) on a NVMe <I>DEVICE</I> 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 <I>DEVICE</I> then parts of the NVMe Identify controller and namespace +response are translated to a SCSI standard INQUIRY response which is then +decoded and output. +<P> + +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). +<P> + +The following SCSI commands are currently supported by the SNTL library: +INQUIRY, MODE SELECT(10), MODE SENSE(10), READ(10,16), READ CAPACITY(10,16), +RECEIVE DIAGNOSTIC RESULTS, REQUEST SENSE, REPORT LUNS, REPORT SUPPORTED +OPERATION CODES, REPORT SUPPORTED TASK MANAGEMENT FUNCTIONS, SEND +DIAGNOSTICS, START STOP UNIT, SYNCHRONIZE CACHE(10,16), TEST UNIT READY, +VERIFY(10,16), WRITE(10,16) and WRITE SAME(10,16). +<A NAME="lbAK"> </A> +<H2>EXIT STATUS</H2> + +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. +<P> + +The exit status values listed below can be given to the sg_decode_sense +utility (which is found in this package) as follows: +<BR> + +<BR> sg_decode_sense --err=<exit_status> +<BR> + +and a short explanatory string will be output to stdout. +<P> + +The exit status values are: +<DL COMPACT> +<DT><B>0</B> + +<DD> +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. +<DT><B>1</B> + +<DD> +syntax error. Either illegal command line options, options with bad +arguments or a combination of options that is not permitted. +<DT><B>2</B> + +<DD> +the <I>DEVICE</I> reports that it is not ready for the operation requested. +The <I>DEVICE</I> 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 +<I>DEVICE</I> may be temporarily blocked while error recovery is taking place. +<DT><B>3</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>5</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>6</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>7</B> + +<DD> +the <I>DEVICE</I> reports a "data protect" sense key. This implies some +mechanism has blocked writes (or possibly all access to the media). +<DT><B>9</B> + +<DD> +the <I>DEVICE</I> reports an illegal request with an additional sense code +of "invalid command operation code" which means that it doesn't support the +requested command. +<DT><B>10</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>11</B> + +<DD> +the <I>DEVICE</I> reports an aborted command. In some cases aborted +commands can be retried immediately (e.g. if the transport aborted +the command due to congestion). +<DT><B>14</B> + +<DD> +the <I>DEVICE</I> reports a miscompare sense key. VERIFY and COMPARE AND +WRITE commands may report this. +<DT><B>15</B> + +<DD> +the utility is unable to open, close or use the given <I>DEVICE</I> 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. +<DT><B>17</B> + +<DD> +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. +<DT><B>18</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>20</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>21</B> + +<DD> +the <I>DEVICE</I> 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 . +<DT><B>22</B> + +<DD> +the <I>DEVICE</I> 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 <I>DEVICE</I> is returned. Since LBAs are origin zero +they range from 0 to n-1 where n is the number of blocks on the <I>DEVICE</I>, +so the LBA of the last block is one less than the total number of blocks. +<DT><B>24</B> + +<DD> +the <I>DEVICE</I> reports a SCSI status of "reservation conflict". This +means access to the <I>DEVICE</I> with the current command has been blocked +because another machine (HBA or SCSI "initiator") holds a reservation on +this <I>DEVICE</I>. On modern SCSI systems this is related to the use of +the PERSISTENT RESERVATION family of commands. +<DT><B>25</B> + +<DD> +the <I>DEVICE</I> reports a SCSI status of "condition met". Currently only +the PRE-FETCH command (see SBC-4) yields this status. +<DT><B>26</B> + +<DD> +the <I>DEVICE</I> 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. +<DT><B>27</B> + +<DD> +the <I>DEVICE</I> reports a SCSI status of "task set full". +<DT><B>28</B> + +<DD> +the <I>DEVICE</I> reports a SCSI status of "ACA active". ACA is "auto +contingent allegiance" and is seldom used. +<DT><B>29</B> + +<DD> +the <I>DEVICE</I> 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". +<DT><B>31</B> + +<DD> +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. +<DT><B>32</B> + +<DD> +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. +<DT><B>33</B> + +<DD> +the command sent to <I>DEVICE</I> has timed out. +<DT><B>34</B> + +<DD> +this is a Windows only exit status and indicates that the Windows error +number (32 bits) cannot meaningfully be mapped to an equivalent Unix error +number returned as the exit status (7 bits). +<DT><B>35</B> + +<DD> +a transport error has occurred. This will either be in the driver (e.g. HBA +driver) or in the interconnect between the host (initiator) and the +device (target). For example in SAS an expander can run out of paths and +thus be unable to return the user data for a READ command. +<DT><B>36</B> + +<DD> +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. +<DT><B>40</B> + +<DD> +the command sent to <I>DEVICE</I> has received an "aborted command" sense +key with an additional sense code of 0x10. This value 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. +<DT><B>41</B> + +<DD> +the command sent to <I>DEVICE</I> 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. +<DT><B>48</B> + +<DD> +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. +<DT><B>49</B> + +<DD> +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 +nonsensical. +<DT><B>50</B> + +<DD> +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. +<DT><B>50 + <os_error_number></B> + +<DD> +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. +<DT><B>97</B> + +<DD> +a SCSI command response failed sanity checks. +<DT><B>98</B> + +<DD> +the <I>DEVICE</I> reports it has a check condition but the error +doesn't fit into any of the above categories. +<DT><B>99</B> + +<DD> +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. +<DT><B>100-125</B> + +<DD> +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. +<DT><B>126</B> + +<DD> +the utility was found but could not be executed. That might occur if the +executable does not have execute permissions. +<DT><B>127</B> + +<DD> +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. +<DT><B>128 + <signum></B> + +<DD> +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 . +<DT><B>255</B> + +<DD> +the utility tried to yield an exit status of 255 or larger. That should +not happen; given here for completeness. +</DL> +<P> + +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. +<A NAME="lbAL"> </A> +<H2>COMMON OPTIONS</H2> + +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). +<P> + +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). +<P> + +Some options are used uniformly in most of the utilities in this +package. Those options are listed below. Note that there are some +exceptions. +<DL COMPACT> +<DT><B>-d</B>, <B>--dry-run</B><DD> +utilities that can cause lots of user data to be lost or overwritten +sometimes have a <I>--dry-run</I> 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 <I>--dry-run</I> +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. <I>--dry_run</I>). +<DT><B>-e</B>, <B>--enumerate</B><DD> +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 <I>DEVICE</I> is ignored (as are most other options) and no +SCSI IO takes place, so the invoker does not need any elevated permissions. +<DT><B>-h</B>, <B>-?</B>, <B>--help</B><DD> +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. +<DT><B>-H</B>, <B>--hex</B><DD> +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. +<DT><B>-i</B>, <B>--in</B>=<I>FN</I><DD> +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 <I>--hex</I> or <I>--raw</I> option and +redirecting the command line output to a file (often done with ">" in Unix +based operating systems). The difference between <I>--hex</I> and +<I>--raw</I> is that the former produces output in ASCII hexadecimal +while <I>--raw</I> 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 <I>--in=FN</I> option where the file name is +<I>FN</I>. If "-" is used for <I>FN</I> 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 <I>--raw</I> option is +also given in which case it is assumed to be binary. Notice that the meaning +of the <I>--raw</I> option is "flipped" when used with <I>--in=FN</I> 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 <I>--hex</I> may need to be used +multiple times (and is more conveniently given as '-HH' or '-HHH). +<DT><B>-i</B>, <B>--inhex</B>=<I>FN</I><DD> +This option has the same or similar functionality as <I>--in=FN</I>. And +perhaps 'inhex' is more descriptive since by default, ASCII hexadecimal is +expected in the contents of file: <I>FN</I>. Alternatively the short form +option may be <I>-I</I> or <I>-X</I>. See the "FORMAT OF FILES CONTAINING +ASCII HEX" section below for more information. +<DT><B>-m</B>, <B>--maxlen</B>=<I>LEN</I><DD> +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 <A HREF="../man8/sg_logs.8.html">sg_logs</A>(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. +<BR> + +To head off a class of degenerate bugs, if <I>LEN</I> is less than 16 then +it is ignored (usually with a warning message) and the default value is +used instead. Some utilities use 4 (bytes), rather than 16, as the cutoff +value. +<DT><B>-r</B>, <B>--raw</B><DD> +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 <I>DEVICE</I> along with the +SCSI command, use this option. Alternatively the <I>--in=FN</I> option causes +<I>DEVICE</I> to be ignored and the response data (to be decoded) fetched +from a file named <I>FN</I>. In these cases this option may indicate that +binary data can be read from stdin or from a nominated file (e.g. <I>FN</I>). +<DT><B>-t</B>, <B>--timeout</B>=<I>SECS</I><DD> +utilities that issue potentially long-running SCSI commands often have a +<I>--timeout=SECS</I> 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, <I>SECS</I>, +is usually in seconds and the short form of the option may be something +other than <I>-t</I> 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 <I>SECS</I>. +<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 <I>--immed</I> option +or a <I>--wait</I> option which is the logical inverse of the "immediate" +action. +<DT><B>-v</B>, <B>--verbose</B><DD> +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. +<DT><B>-V</B>, <B>--version</B><DD> +print the version string and then exit. Each utility has its own version +number and date of last code change. +</DL> +<A NAME="lbAM"> </A> +<H2>NUMERIC ARGUMENTS</H2> + +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. +<P> + +Multiplicative suffixes are accepted. They are one, two or three letter +strings appended directly after the number to which they apply: +<P> + +<BR> c C *1 +<BR> + +<BR> w W *2 +<BR> + +<BR> b B *512 +<BR> + +<BR> k K KiB *1024 +<BR> + +<BR> KB kB *1000 +<BR> + +<BR> m M MiB *1048576 +<BR> + +<BR> MB mB *1000000 +<BR> + +<BR> g G GiB *(2^30) +<BR> + +<BR> GB gB *(10^9) +<BR> + +<BR> t T TiB *(2^40) +<BR> + +<BR> TB *(10^12) +<BR> + +<BR> p P PiB *(2^50) +<BR> + +<BR> PB *(10^15) +<P> + +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. +<P> + +These multiplicative suffixes are compatible with GNU's dd command (since +2002) which claims compliance with SI and with IEC 60027-2. +<P> + +A suffix of the form "x<n>" multiplies the preceding number by <n>. An +example is "2x33" for "66". The left argument cannot be '0' as '0x' will +be interpreted as hexadecimal number prefix (see below). The left +argument to the multiplication must end in a hexadecimal digit (i.e. +0 to f) and the whole expression cannot have any embedded whitespace (e.g. +spaces). An ugly example: "0xfx0x2" for 30. +<P> + +A suffix of the form "+<n>" adds the preceding number to <n>. An example +is "3+1k" for "1027". The left argument to the addition must end in a +hexadecimal digit (i.e. 0 to f) and the whole expression cannot have any +embedded whitespace (e.g. spaces). Another example: "0xf+0x2" for 17. +<P> + +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". +<A NAME="lbAN"> </A> +<H2>FORMAT OF FILES CONTAINING ASCII HEX</H2> + +Such a file is assumed to contain a sequence of one or two digit ASCII +hexadecimal values separated by whitespace. "Whitespace consists of either +spaces, tabs, blank lines, or any combination thereof". Each one or two digit +ASCII hex pair is decoded into a byte (i.e. 8 bits). The following will be +decoded to valid (ascending valued) +bytes: '0', '01', '3', 'c', 'F', '4a', 'cC', 'ff'. +Lines containing only whitespace are ignored. The contents of any line +containing a hash mark ('#') is ignored from that point until the end of that +line. Users are encouraged to use hash marks to introduce comments in hex +files. The author uses the extension'.hex' on such files. Examples can be +found in the 'inhex' directory. +<A NAME="lbAO"> </A> +<H2>MICROCODE AND FIRMWARE</H2> + +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. +<A NAME="lbAP"> </A> +<H2>SCRIPTS, EXAMPLES and UTILS</H2> + +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. +<P> + +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). +<P> + +Some utilities that the author has found useful have been placed in +the 'utils' subdirectory. +<A NAME="lbAQ"> </A> +<H2>WEB SITE</H2> + +There is a web page discussing this package at +<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 +package on various operating systems is discussed at: +<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 +<A HREF="https://github.com/hreinecke/sg3_utils">https://github.com/hreinecke/sg3_utils</A> . 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. +<A NAME="lbAR"> </A> +<H2>AUTHORS</H2> + +Written by Douglas Gilbert. Some utilities have been contributed, see the +CREDITS file and individual source files (in the 'src' directory). +<A NAME="lbAS"> </A> +<H2>REPORTING BUGS</H2> + +Report bugs to <dgilbert at interlog dot com>. +<A NAME="lbAT"> </A> +<H2>COPYRIGHT</H2> + +Copyright © 1999-2021 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. +<A NAME="lbAU"> </A> +<H2>SEE ALSO</H2> + +<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> + +<P> + +<HR> +<A NAME="index"> </A><H2>Index</H2> +<DL> +<DT><A HREF="#lbAB">NAME</A><DD> +<DT><A HREF="#lbAC">SYNOPSIS</A><DD> +<DT><A HREF="#lbAD">DESCRIPTION</A><DD> +<DT><A HREF="#lbAE">ENVIRONMENT VARIABLES</A><DD> +<DT><A HREF="#lbAF">LINUX DEVICE NAMING</A><DD> +<DT><A HREF="#lbAG">WINDOWS DEVICE NAMING</A><DD> +<DT><A HREF="#lbAH">FREEBSD DEVICE NAMING</A><DD> +<DT><A HREF="#lbAI">SOLARIS DEVICE NAMING</A><DD> +<DT><A HREF="#lbAJ">NVME SUPPORT</A><DD> +<DT><A HREF="#lbAK">EXIT STATUS</A><DD> +<DT><A HREF="#lbAL">COMMON OPTIONS</A><DD> +<DT><A HREF="#lbAM">NUMERIC ARGUMENTS</A><DD> +<DT><A HREF="#lbAN">FORMAT OF FILES CONTAINING ASCII HEX</A><DD> +<DT><A HREF="#lbAO">MICROCODE AND FIRMWARE</A><DD> +<DT><A HREF="#lbAP">SCRIPTS, EXAMPLES and UTILS</A><DD> +<DT><A HREF="#lbAQ">WEB SITE</A><DD> +<DT><A HREF="#lbAR">AUTHORS</A><DD> +<DT><A HREF="#lbAS">REPORTING BUGS</A><DD> +<DT><A HREF="#lbAT">COPYRIGHT</A><DD> +<DT><A HREF="#lbAU">SEE ALSO</A><DD> +</DL> +<HR> +This document was created by +<A HREF="/cgi-bin/man/man2html">man2html</A>, +using the manual pages.<BR> +Time: 03:12:28 GMT, November 11, 2021 +</BODY> +</HTML> |