{ "content": [ { "type": "text", "text": "# sg3_utils (man)\n\n## NAME\n\nsg3utils - a package of utilities for sending SCSI commands\n\n## SYNOPSIS\n\nsg* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN] [--maxlen=LEN] [--raw]\n[--timeout=SECS] [--verbose] [--version] [OTHEROPTIONS] DEVICE\n\n## DESCRIPTION\n\nsg3utils is a package of utilities that send SCSI commands to the given DEVICE via a SCSI\npass through interface provided by the host operating system.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **ENVIRONMENT VARIABLES**\n- **LINUX DEVICE NAMING**\n- **WINDOWS DEVICE NAMING**\n- **FREEBSD DEVICE NAMING**\n- **SOLARIS DEVICE NAMING**\n- **NVME SUPPORT**\n- **EXIT STATUS** (2 subsections)\n- **COMMON OPTIONS** (11 subsections)\n- **NUMERIC ARGUMENTS**\n- **FORMAT OF FILES CONTAINING ASCII HEX**\n- **MICROCODE AND FIRMWARE** (1 subsections)\n- **WEB SITE**\n- **AUTHORS**\n- **REPORTING BUGS**\n- **COPYRIGHT**\n- **SEE ALSO** (1 subsections)\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "sg3_utils", "section": "", "mode": "man", "summary": "sg3utils - a package of utilities for sending SCSI commands", "synopsis": "sg* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN] [--maxlen=LEN] [--raw]\n[--timeout=SECS] [--verbose] [--version] [OTHEROPTIONS] DEVICE", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-d", "long": "--dry-run", "arg": null, "description": "utilities that can cause lots of user data to be lost or overwritten sometimes have a --dry-run option. Device modifying actions are typically bypassed (or skipped) to im‐ plement 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 --dry-run op‐ tion has become a common feature of many command line utilities (e.g. the Unix 'patch' command), not just those from this package. Note that most hyphenated option names in this package also can be given with an un‐ derscore rather than a hyphen (e.g. --dryrun)." }, { "flag": "-e", "long": "--enumerate", "arg": null, "description": "some utilities (e.g. sgses and sgvpd) 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 DEVICE is ignored (as are most other options) and no SCSI IO takes place, so the invoker does not need any elevated permissions." }, { "flag": "-?", "long": "--help", "arg": null, "description": "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." }, { "flag": "-H", "long": "--hex", "arg": null, "description": "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. with‐ out a relative address to the left and without trailing ASCII) use this option three or four times." }, { "flag": "-i", "long": "--in", "arg": null, "description": "many SCSI commands fetch a significant amount of data (returned in the data-in buffer) which several of these utilities decode (e.g. sgvpd and sglogs). 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 --hex or --raw option and redirecting the command line output to a file (often done with \">\" in Unix based operating systems). The difference between --hex and --raw is that the former produces output in ASCII hexadecimal while --raw produces its output in \"raw\" binary. The second step (i.e. decoding the SCSI response data now held in a file) can be done using this --in=FN option where the file name is FN. If \"-\" is used for FN 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 --raw option is also given in which case it is assumed to be binary. Notice that the meaning of the --raw option is \"flipped\" when used with --in=FN to act on the input, typically it acts on the out‐ put data. 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 --hex may need to be used multiple times (and is more conveniently given as '-HH' or '-HHH)." }, { "flag": "-i", "long": "--inhex", "arg": null, "description": "This option has the same or similar functionality as --in=FN. And perhaps 'inhex' is more descriptive since by default, ASCII hexadecimal is expected in the contents of file: FN. Alternatively the short form option may be -I or -X. See the \"FORMAT OF FILES CONTAINING ASCII HEX\" section below for more information." }, { "flag": "-m", "long": "--maxlen", "arg": null, "description": "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 ac‐ count. 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 allo‐ cation length (sometimes recommended in the SCSI draft standards) or a \"double fetch\" strategy. See sglogs(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." }, { "flag": "-r", "long": "--raw", "arg": null, "description": "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. Some utilities that consume data to send to the DEVICE along with the SCSI command, use this option. Alternatively the --in=FN option causes DEVICE to be ignored and the response data (to be decoded) fetched from a file named FN. In these cases this option may indicate that binary data can be read from stdin or from a nominated file (e.g. FN)." }, { "flag": "-t", "long": "--timeout", "arg": null, "description": "utilities that issue potentially long-running SCSI commands often have a --time‐ out=SECS option. This typically instructs the operating system to abort the SCSI com‐ mand 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, SECS, is usually in seconds and the short form of the option may be something other than -t 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 ac‐ tual command timeout given to the operating systems is the higher of the internal timeout and SECS. 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 RE‐ QUEST SENSE command can be used to monitor progress with its progress indication field (see the sgrequests and sgturs utilities). Utilities that send such SCSI command either have an --immed option or a --wait option which is the logical inverse of the \"immediate\" action." }, { "flag": "-v", "long": "--verbose", "arg": null, "description": "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 al‐ ways sent to stderr." }, { "flag": "-V", "long": "--version", "arg": null, "description": "print the version string and then exit. Each utility has its own version number and date of last code change." } ], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 3, "subsections": [] }, { "name": "DESCRIPTION", "lines": 64, "subsections": [] }, { "name": "ENVIRONMENT VARIABLES", "lines": 21, "subsections": [] }, { "name": "LINUX DEVICE NAMING", "lines": 26, "subsections": [] }, { "name": "WINDOWS DEVICE NAMING", "lines": 34, "subsections": [] }, { "name": "FREEBSD DEVICE NAMING", "lines": 13, "subsections": [] }, { "name": "SOLARIS DEVICE NAMING", "lines": 31, "subsections": [] }, { "name": "NVME SUPPORT", "lines": 37, "subsections": [] }, { "name": "EXIT STATUS", "lines": 162, "subsections": [ { "name": "100-125", "lines": 10 }, { "name": "128 + ", "lines": 12 } ] }, { "name": "COMMON OPTIONS", "lines": 10, "subsections": [ { "name": "-d --dry-run", "lines": 9, "flag": "-d", "long": "--dry-run" }, { "name": "-e --enumerate", "lines": 6, "flag": "-e", "long": "--enumerate" }, { "name": "-h -? --help", "lines": 4, "flag": "-?", "long": "--help" }, { "name": "-H --hex", "lines": 5, "flag": "-H", "long": "--hex" }, { "name": "-i --in", "lines": 19, "flag": "-i", "long": "--in" }, { "name": "-i --inhex", "lines": 5, "flag": "-i", "long": "--inhex" }, { "name": "-m --maxlen", "lines": 11, "flag": "-m", "long": "--maxlen" }, { "name": "-r --raw", "lines": 9, "flag": "-r", "long": "--raw" }, { "name": "-t --timeout", "lines": 18, "flag": "-t", "long": "--timeout" }, { "name": "-v --verbose", "lines": 4, "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "lines": 3, "flag": "-V", "long": "--version" } ] }, { "name": "NUMERIC ARGUMENTS", "lines": 44, "subsections": [] }, { "name": "FORMAT OF FILES CONTAINING ASCII HEX", "lines": 9, "subsections": [] }, { "name": "MICROCODE AND FIRMWARE", "lines": 5, "subsections": [ { "name": "SCRIPTS, EXAMPLES and UTILS", "lines": 15 } ] }, { "name": "WEB SITE", "lines": 9, "subsections": [] }, { "name": "AUTHORS", "lines": 3, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "COPYRIGHT", "lines": 7, "subsections": [] }, { "name": "SEE ALSO", "lines": 1, "subsections": [ { "name": "sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)", "lines": 1 } ] } ], "sections": { "NAME": { "content": "sg3utils - a package of utilities for sending SCSI commands\n", "subsections": [] }, "SYNOPSIS": { "content": "sg* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN] [--maxlen=LEN] [--raw]\n[--timeout=SECS] [--verbose] [--version] [OTHEROPTIONS] DEVICE\n", "subsections": [] }, "DESCRIPTION": { "content": "sg3utils is a package of utilities that send SCSI commands to the given DEVICE via a SCSI\npass through interface provided by the host operating system.\n\nThe names of all utilities start with \"sg\" and most start with \"sg\" often followed by the\nname, or a shortening of the name, of the SCSI command that they send. For example the\n\"sgverify\" utility sends the SCSI VERIFY command. A mapping between SCSI commands and the\nsg3utils utilities that issue them is shown in the COVERAGE file. The sgraw utility can be\nused to send an arbitrary SCSI command (supplied on the command line) to the given DEVICE.\n\nsgdecodesense can be used to decode SCSI sense data given on the command line or in a file.\nsgraw -vvv will output the T10 name of a given SCSI CDB which is most often 16 bytes or less\nin length.\n\nSCSI draft standards can be found at http://www.t10.org . The standards themselves can be\npurchased from ANSI and other standards organizations. A good overview of various SCSI stan‐\ndards can be seen in http://www.t10.org/scsi-3.htm with the SCSI command sets in the upper\npart of the diagram. The highest level (i.e. most abstract) document is the SCSI Architecture\nModel (SAM) with SAM-5 being the most recent standard (ANSI INCITS 515-2016) with the most\nrecent draft being SAM-6 revision 4 . SCSI commands in common with all device types can be\nfound in SCSI Primary Commands (SPC) of which SPC-4 is the most recent standard (ANSI INCITS\n513-2015). The most recent SPC draft is SPC-5 revision 21. Block device specific commands\n(e.g. as used by disks) are in SBC, those for tape drives in SSC, those for SCSI enclosures\nin SES and those for CD/DVD/BD drives in MMC.\n\nIt is becoming more common to control ATA disks with the SCSI command set. This involves the\ntranslation of SCSI commands to their corresponding ATA equivalents (and that is an imperfect\nmapping in some cases). The relevant standard is called SCSI to ATA Translation (SAT, SAT-2\nand SAT-3) are now standards at INCITS(ANSI) and ISO while SAT-4 is at the draft stage. The\nlogic to perform the command translation is often called a SAT Layer or SATL and may be\nwithin an operating system, in host bus adapter firmware or in an external device (e.g. asso‐\nciated with a SAS expander). See http://www.t10.org for more information.\n\nThere is some support for SCSI tape devices but not for their basic operation. The reader is\nreferred to the \"mt\" utility.\n\nThere are two generations of command line option usage. The newer utilities (written since\nJuly 2004) use the getoptlong() function to parse command line options. With that function,\neach option has two representations: a short form (e.g. '-v') and a longer form (e.g. '--ver‐\nbose'). If an argument is required then it follows a space (optionally) in the short form and\na \"=\" in the longer form (e.g. in the sgverify utility '-l 2a6h' and '--lba=2a6h' are equiv‐\nalent). Note that with getoptlong(), short form options can be elided, for example: '-all'\nis equivalent to '-a -l -l'. The DEVICE argument may appear after, between or prior to any\noptions.\n\nThe older utilities, including as sginq, sglogs, sgmodes, sgopcode, sgrbuff, sgread‐\ncap, sgsenddiag, sgstart and sgturs had individual command line processing code typically\nbased on a single \"-\" followed by one or more characters. If an argument is needed then it\nfollows a \"=\" ( e.g. '-p=1f' in sgmodes with its older interface). Various options can be\nelided as long as it is not ambiguous (e.g. '-vv' to increase the verbosity).\n\nOver time the command line interface of these older utilities became messy and overloaded\nwith options. So in sg3utils version 1.23 the command line interface of these older utili‐\nties was altered to have both a cleaner getoptlong() interface and their older interface for\nbackward compatibility. By default these older utilities use their getoptlong() based in‐\nterface. The getoptlong() is a GNU extension (i.e. not yet POSIX certified) but more recent\ncommand line utilities tend to use it. That can be overridden by defining the\nSG3UTILSOLDOPTS environment variable or using '-O' or '--old' as the first command line\noption. The man pages of the older utilities documents the details.\n\nSeveral sg3utils utilities are based on the Unix dd command (e.g. sgdd) and permit copying\ndata at the level of SCSI READ and WRITE commands. sgdd is tightly bound to Linux and hence\nis not ported to other OSes. A more generic utility (than sgdd) called ddpt in a package of\nthe same name has been ported to other OSes.\n", "subsections": [] }, "ENVIRONMENT VARIABLES": { "content": "The SG3UTILSOLDOPTS environment variable is explained in the previous section. It is only\nfor backward compatibility of the command line options for older utilities.\n\nThe SG3UTILSDSENSE environment variable may be set to a number. It is only used by the em‐\nbedded SNTL within the library used by the utilities in this library. SNTL is a SCSI to NVMe\nTranslation Layer. This environment variable defaults to 0 which will lead to any utility\nthat issues a SCSI command that is translated to a NVMe command (by the embedded SNTL) that\nfails at the NVMe dvice, to return SCSI sense in 'fixed' format. If this variable is non-zero\nthen then the returned SCSI sense will be in 'descriptor' format.\n\nSeveral utilities have their own environment variable setting (e.g. sgpersist has SGPER‐\nSISTINRDONLY). See individual utility man pages for more information.\n\nThere is a Linux specific environment variable called SG3UTILSLINUXNANO that if defined\nand the sg driver in the system is 4.0.30 or later, will show command durations in nanosec‐\nonds rather than the default milliseconds. Command durations are typically only shown if\n--verbose is used 3 or more times. Due to an interface problem (a 32 bit integer that should\nbe 64 bits with the benefit of hindsight) the maximum duration that can be represented in\nnanoseconds is about 4.2 seconds. If longer durations may occur then don't define this envi‐\nronment variable (or undefine it).\n", "subsections": [] }, "LINUX DEVICE NAMING": { "content": "Most disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc, etc. SCSI disks in\nLinux have always had names like that but in recent Linux kernels it has become more common\nfor many other disks (including SATA disks and USB storage devices) to be named like that.\nPartitions within a disk are specified by a number appended to the device name, starting at 1\n(e.g. /dev/sda1 ).\n\nTape drives are named /dev/st or /dev/nst where starts at zero. Additionally\none letter from this list: \"lma\" may be appended to the name. CD, DVD and BD readers (and\nwriters) are named /dev/sr where start at zero. There are less used SCSI device\ntype names, the dmesg and the lsscsi commands may help to find if any are attached to a run‐\nning system.\n\nThere is also a SCSI device driver which offers alternate generic access to SCSI devices. It\nuses names of the form /dev/sg where starts at zero. The \"lsscsi -g\" command may\nbe useful in finding these and which generic name corresponds to a device type name (e.g.\n/dev/sg2 may correspond to /dev/sda). In the lk 2.6 series a block SCSI generic driver was\nintroduced and its names are of the form /dev/bsg/ where h, c, t and l are numbers.\nAgain see the lsscsi command to find the correspondence between that SCSI tuple (i.e.\n) and alternate device names.\n\nPrior to the Linux kernel 2.6 series these utilities could only use generic device names\n(e.g. /dev/sg1 ). In almost all cases in the Linux kernel 2.6 series, any device name can be\nused by these utilities.\n\nVery little has changed in Linux device naming in the Linux kernel 3 and 4 series.\n", "subsections": [] }, "WINDOWS DEVICE NAMING": { "content": "Storage and related devices can have several device names in Windows. Probably the most com‐\nmon in the volume name (e.g. \"D:\"). There are also a \"class\" device names such as \"Physi‐\ncalDrive\", \"CDROM\" and \"TAPE\". is an integer starting at 0 allocated in ascend‐\ning order as devices are discovered (and sometimes rediscovered).\n\nSome storage devices have a SCSI lower level device name which starts with a SCSI (pseudo)\nadapter name of the form \"SCSI:\". To this is added sub-addressing in the form of a \"bus\"\nnumber, a \"target\" identifier and a LUN (Logical Unit Number). The \"bus\" number is also known\nas a \"PathId\". These are assembled to form a device name of the form: \"SCSI:,,\". The trailing \",\" may be omitted in which case a LUN of zero is assumed.\nThis lower level device name cannot often be used directly since Windows blocks attempts to\nuse it if a class driver has \"claimed\" the device. There are SCSI device types (e.g. Automa‐\ntion/Drive interface type) for which there is no class driver. At least two transports (\"bus\ntypes\" in Windows jargon): USB and IEEE 1394 do not have a \"scsi\" device names of this form.\n\nIn keeping with DOS file system conventions, the various device names can be given in upper,\nlower or mixed case. Since \"PhysicalDrive\" is tedious to write, a shortened form of\n\"PD\" is permitted by all utilities in this package.\n\nA single device (e.g. a disk) can have many device names. For example: \"PD0\" can also be\n\"C:\", \"D:\" and \"SCSI0:0,1,0\". The two volume names reflect that the disk has two partitions\non it. Disk partitions that are not recognized by Windows are not usually given a volume\nname. However Vista does show a volume name for a disk which has no partitions recognized by\nit and when selected invites the user to format it (which may be rather unfriendly to other\nOSes).\n\nThese utilities assume a given device name is in the Win32 device namespace. To make that\nexplicit \"\\\\.\\\" can be prepended to the device names mentioned in this section. Beware that\nbackslash is an escape character in Unix like shells and the C programming language. In a\nshell like Msys (from MinGW) each backslash may need to be typed twice.\n\nThe sgscan utility within this package lists out Windows device names in a form that is\nsuitable for other utilities in this package to use.\n", "subsections": [] }, "FREEBSD DEVICE NAMING": { "content": "SCSI disks have block names of the form /dev/da where is an integer starting at\nzero. The \"da\" is replaced by \"sa\" for SCSI tape drives and \"cd\" for SCSI CD/DVD/BD drives.\nEach SCSI device has a corresponding pass-through device name of the form /dev/pass\nwhere is an integer starting at zero. The \"camcontrol devlist\" command may be useful\nfor finding out which SCSI device names are available and the correspondence between class\nand pass-through names.\n\nFreeBSD allows device names to be given without the leading \"/dev/\" (e.g. da0 instead of\n/dev/da0). That worked in this package up until version 1.43 when the unadorned device name\n(e.g. \"da0\") gave an error. The original action (i.e. allowing unadorned device names) has\nbeen restored in version 1.46 . Also note that symlinks (to device names) are followed before\nprepending \"/dev/\" if the resultant name doesn't start with a \"/\".\n", "subsections": [] }, "SOLARIS DEVICE NAMING": { "content": "SCSI device names below the /dev directory have a form like: c5t4d3s2 where the number fol‐\nlowing \"c\" is the controller (HBA) number, the number following \"t\" is the target number\n(from the SCSI parallel interface days) and the number following \"d\" is the LUN. Following\nthe \"s\" is the slice number which is related to a partition and by convention \"s2\" is the\nwhole disk.\n\nOpenSolaris also has a c5t4d3p2 form where the number following the \"p\" is the partition num‐\nber apart from \"p0\" which is the whole disk. So a whole disk may be referred to as either\nc5t4d3, c5t4d3s2 or c5t4d3p0 .\n\nAnd these device names are duplicated in the /dev/dsk and /dev/rdsk directories. The former\nis the block device name and the latter is for \"raw\" (or char device) access which is what\nsg3utils needs. So in OpenSolaris something of the form 'sginq /dev/rdsk/c5t4d3p0' should\nwork. If it doesn't work then add a '-vvv' option for more debug information. Trying this\nform 'sginq /dev/dsk/c5t4d3p0' (note \"rdsk\" changed to \"dsk\") will result in an \"inappropri‐\nate ioctl for device\" error.\n\nThe device names within the /dev directory are typically symbolic links to much longer topo‐\nlogical names in the /device directory. In Solaris cd/dvd/bd drives seem to be treated as\ndisks and so are found in the /dev/rdsk directory. Tape drives appear in the /dev/rmt direc‐\ntory.\n\nThere is also a sgen (SCSI generic) driver which by default does not attach to any device.\nSee the /kernel/drv/sgen.conf file to control what is attached. Any attached device will have\na device name of the form /dev/scsi/c5t4d3 .\n\nListing available SCSI devices in Solaris seems to be a challenge. \"Use the 'format' command\"\nadvice works but seems a very dangerous way to list devices. [It does prompt again before do‐\ning any damage.] 'devfsadm -Cv' cleans out the clutter in the /dev/rdsk directory, only leav‐\ning what is \"live\". The \"cfgadm -v\" command looks promising.\n", "subsections": [] }, "NVME SUPPORT": { "content": "NVMe (or NVM Express) is a relatively new storage transport and command set. The level of ab‐\nstraction of the NVMe command set is somewhat lower the SCSI command sets, closer to the\nlevel of abstraction of ATA (and SATA) command sets. NVMe claims to be designed with flash\nand modern \"solid state\" storage in mind, something unheard of when SCSI was originally de‐\nveloped in the 1980s.\n\nThe SCSI command sets' advantage is the length of time they have been in place and the exist‐\ning tools (like these) to support it. Plus SCSI command sets level of abstraction is both and\nadvantage and disadvantage. Recently the NVME-MI (Management Interface) designers decide to\nuse the SCSI Enclosure Services (SES-3) standard \"as is\" with the addition of two tunnelling\nNVME-MI commands: SES Send and SES Receive. This means after the OS interface differences are\ntaken into account, the sgses, sgsesmicrocode and sgsenddiag utilities can be used on a\nNVMe device that supports a newer version of NVME-MI.\n\nThe NVME-MI SES Send and SES Receive commands correspond to the SCSI SEND DIAGNOSTIC and RE‐\nCEIVE DIAGNOSTIC RESULTS commands respectively. There are however a few other commands that\nneed to be translated, the most important of which is the SCSI INQUIRY command to the NVMe\nIdentify controller/namespace. Starting in version 1.43 these utilities contain a small SNTL\n(SCSI to NVMe Translation Layer) to take care of these details.\n\nAs a side effect of this \"juggling\" if the sginq utility is used (without the --page= op‐\ntion) on a NVMe DEVICE then the actual NVMe Identifier (controller and possibly namespace)\nresponses are decoded and output. However if 'sginq --page=sinq ' is given for the\nsame DEVICE then parts of the NVMe Identify controller and namespace response are translated\nto a SCSI standard INQUIRY response which is then decoded and output.\n\nApart from the special case with the sginq, all other utilities in the package assume they\nare talking to a SCSI device and decode any response accordingly. One easy way for users to\nsee the underlying device is a NVMe device is the standard INQUIRY response Vendor Identifi‐\ncation field of \"NVMe \" (an 8 character long string with 4 spaces to the right).\n\nThe following SCSI commands are currently supported by the SNTL library: INQUIRY, MODE SE‐\nLECT(10), MODE SENSE(10), READ(10,16), READ CAPACITY(10,16), RECEIVE DIAGNOSTIC RESULTS, RE‐\nQUEST SENSE, REPORT LUNS, REPORT SUPPORTED OPERATION CODES, REPORT SUPPORTED TASK MANAGEMENT\nFUNCTIONS, SEND DIAGNOSTICS, START STOP UNIT, SYNCHRONIZE CACHE(10,16), TEST UNIT READY, VER‐\nIFY(10,16), WRITE(10,16) and WRITE SAME(10,16).\n", "subsections": [] }, "EXIT STATUS": { "content": "To aid scripts that call these utilities, the exit status is set to indicate success (0) or\nfailure (1 or more). Note that some of the lower values correspond to the SCSI sense key val‐\nues.\n\nThe exit status values listed below can be given to the sgdecodesense utility (which is\nfound in this package) as follows:\nsgdecodesense --err=\nand a short explanatory string will be output to stdout.\n\nThe exit status values are:\n\n0 success. Also used for some utilities that wish to return a boolean value for the\n\"true\" case (and that no error has occurred). The false case is conveyed by exit sta‐\ntus 36.\n\n1 syntax error. Either illegal command line options, options with bad arguments or a\ncombination of options that is not permitted.\n\n2 the DEVICE reports that it is not ready for the operation requested. The DEVICE may\nbe in the process of becoming ready (e.g. spinning up but not at speed) so the util‐\nity may work after a wait. In Linux the DEVICE may be temporarily blocked while error\nrecovery is taking place.\n\n3 the DEVICE reports a medium or hardware error (or a blank check). For example an at‐\ntempt to read a corrupted block on a disk will yield this value.\n\n5 the DEVICE reports an \"illegal request\" with an additional sense code other than \"in‐\nvalid command operation code\". This is often a supported command with a field set re‐\nquesting an unsupported capability. For commands that require a \"service action\" field\nthis value can indicate that the command with that service action value is not sup‐\nported.\n\n6 the DEVICE reports a \"unit attention\" condition. This usually indicates that something\nunrelated to the requested command has occurred (e.g. a device reset) potentially be‐\nfore the current SCSI command was sent. The requested command has not been executed by\nthe device. Note that unit attention conditions are usually only reported once by a\ndevice.\n\n7 the DEVICE reports a \"data protect\" sense key. This implies some mechanism has blocked\nwrites (or possibly all access to the media).\n\n9 the DEVICE reports an illegal request with an additional sense code of \"invalid com‐\nmand operation code\" which means that it doesn't support the requested command.\n\n10 the DEVICE reports a \"copy aborted\". This implies another command or device problem\nhas stopped a copy operation. The EXTENDED COPY family of commands (including WRITE\nUSING TOKEN) may return this sense key.\n\n11 the DEVICE reports an aborted command. In some cases aborted commands can be retried\nimmediately (e.g. if the transport aborted the command due to congestion).\n\n14 the DEVICE reports a miscompare sense key. VERIFY and COMPARE AND WRITE commands may\nreport this.\n\n15 the utility is unable to open, close or use the given DEVICE or some other file. The\ngiven file name could be incorrect or there may be permission problems. Adding the\n'-v' option may give more information.\n\n17 a SCSI \"Illegal request\" sense code received with a flag indicating the Info field is\nvalid. This is often a LBA but its meaning is command specific.\n\n18 the DEVICE reports a medium or hardware error (or a blank check) with a flag indicat‐\ning the Info field is valid. This is often a LBA (of the first encountered error) but\nits meaning is command specific.\n\n20 the DEVICE reports it has a check condition but \"no sense\" and non-zero information in\nits additional sense codes. Some polling commands (e.g. REQUEST SENSE) can receive\nthis response. There may be useful information in the sense data such as a progress\nindication.\n\n21 the DEVICE reports a \"recovered error\". The requested command was successful. Most\nlikely a utility will report a recovered error to stderr and continue, probably leav‐\ning the utility with an exit status of 0 .\n\n22 the DEVICE reports that the current command or its parameters imply a logical block\naddress (LBA) that is out of range. This happens surprisingly often when trying to ac‐\ncess the last block on a storage device; either a classic \"off by one\" logic error or\na misreading of the response from READ CAPACITY(10 or 16) in which the address of the\nlast block rather than the number of blocks on the DEVICE is returned. Since LBAs are\norigin zero they range from 0 to n-1 where n is the number of blocks on the DEVICE, so\nthe LBA of the last block is one less than the total number of blocks.\n\n24 the DEVICE reports a SCSI status of \"reservation conflict\". This means access to the\nDEVICE with the current command has been blocked because another machine (HBA or SCSI\n\"initiator\") holds a reservation on this DEVICE. On modern SCSI systems this is re‐\nlated to the use of the PERSISTENT RESERVATION family of commands.\n\n25 the DEVICE reports a SCSI status of \"condition met\". Currently only the PRE-FETCH com‐\nmand (see SBC-4) yields this status.\n\n26 the DEVICE reports a SCSI status of \"busy\". SAM-6 defines this status as the logical\nunit is temporarily unable to process a command. It is recommended to re-issue the\ncommand.\n\n27 the DEVICE reports a SCSI status of \"task set full\".\n\n28 the DEVICE reports a SCSI status of \"ACA active\". ACA is \"auto contingent allegiance\"\nand is seldom used.\n\n29 the DEVICE reports a SCSI status of \"task aborted\". SAM-5 says: \"This status shall be\nreturned if a command is aborted by a command or task management function on another\nIT nexus and the Control mode page TAS bit is set to one\".\n\n31 error involving two or more command line options. They may be contradicting, select an\nunsupported mode, or a required option (given the context) is missing.\n\n32 there is a logic error in the utility. It corresponds to code comments like\n\"shouldn't/can't get here\". Perhaps the author should be informed.\n\n33 the command sent to DEVICE has timed out.\n\n34 this is a Windows only exit status and indicates that the Windows error number (32\nbits) cannot meaningfully be mapped to an equivalent Unix error number returned as the\nexit status (7 bits).\n\n36 no error has occurred plus the utility wants to convey a boolean value of false. The\ncorresponding true value is conveyed by a 0 exit status.\n\n40 the command sent to DEVICE has received an \"aborted command\" sense key with an addi‐\ntional sense code of 0x10. This value is related to problems with protection informa‐\ntion (PI or DIF). For example this error may occur when reading a block on a drive\nthat has never been written (or is unmapped) if that drive was formatted with type 1,\n2 or 3 protection.\n\n41 the command sent to DEVICE has received an \"aborted command\" sense key with an addi‐\ntional sense code of 0x10 (as with error code) plus a flag indicating the Info field\nis valid.\n\n48 this is an internal message indicating a NVMe status field (SF) is other than zero af‐\nter a command has been executed (i.e. something went wrong). Work in this area is\ncurrently experimental.\n\n49 low level driver reports a response's residual count (i.e. number of bytes actually\nreceived by HBA is 'requestedbytes - residualcount') that is nonsensical.\n\n50 OS system calls that fail often return a small integer number to help. In Unix these\nare called \"errno\" values where 0 implies no error. These error codes set aside 51 to\n96 for mapping these errno values but that may not be sufficient. Higher errno values\nthat cannot be mapped are all mapped to this value (i.e. 50).\nNote that an errno value of 0 is mapped to error code 0.\n\n50 + \nOS system calls that fail often return a small integer number to help indicate what\nthe error is. For example in Unix the inability of a system call to allocate memory\nreturns (in 'errno') ENOMEM which often is associated with the integer 12. So 62 (i.e.\n'50 + 12') may be returned by a utility in this case. It is also possible that a util‐\nity in this package reports 50+ENOMEM when it can't allocate memory, not necessarily\nfrom an OS system call. In recent versions of Linux the file showing the mapping be‐\ntween symbolic constants (e.g. ENOMEM) and the corresponding integer is in the kernel\nsource code file: include/uapi/asm-generic/errno-base.h\nNote that errno values that are greater than or equal to 47 cannot fit in range pro‐\nvided. Instead they are all mapped to 50 as discussed in the previous entry.\n\n97 a SCSI command response failed sanity checks.\n\n98 the DEVICE reports it has a check condition but the error doesn't fit into any of the\nabove categories.\n\n99 any errors that can't be categorized into values 1 to 98 may yield this value. This\nincludes transport and operating system errors after the command has been sent to the\ndevice.\n", "subsections": [ { "name": "100-125", "content": "these error codes are used by the ddpt utility which uses the sg3utils library. They\nare mainly specialized error codes associated with offloaded copies.\n\n126 the utility was found but could not be executed. That might occur if the executable\ndoes not have execute permissions.\n\n127 This is the exit status for utility not found. That might occur when a script calls a\nutility in this package but the PATH environment variable has not been properly set\nup, so the script cannot find the executable.\n" }, { "name": "128 + ", "content": "If a signal kills a utility then the exit status is 128 plus the signal number. For\nexample if a segmentation fault occurs then a utility is typically killed by SIGSEGV\nwhich according to 'man 7 signal' has an associated signal number of 11; so the exit\nstatus will be 139 .\n\n255 the utility tried to yield an exit status of 255 or larger. That should not happen;\ngiven here for completeness.\n\nMost of the error conditions reported above will be repeatable (an example of one that is not\nis \"unit attention\") so the utility can be run again with the '-v' option (or several) to ob‐\ntain more information.\n" } ] }, "COMMON OPTIONS": { "content": "Arguments to long options are mandatory for short options as well. In the short form an argu‐\nment to an option uses zero or more spaces as a separator (i.e. the short form does not use\n\"=\" as a separator).\n\nIf an option takes a numeric argument then that argument is assumed to be decimal unless oth‐\nerwise indicated (e.g. with a leading \"0x\", a trailing \"h\" or as noted in the usage message).\n\nSome options are used uniformly in most of the utilities in this package. Those options are\nlisted below. Note that there are some exceptions.\n", "subsections": [ { "name": "-d --dry-run", "content": "utilities that can cause lots of user data to be lost or overwritten sometimes have a\n--dry-run option. Device modifying actions are typically bypassed (or skipped) to im‐\nplement a policy of \"do no harm\". This allows complex command line invocations to be\ntested before the action required (e.g. format a disk) is performed. The --dry-run op‐\ntion has become a common feature of many command line utilities (e.g. the Unix\n'patch' command), not just those from this package.\nNote that most hyphenated option names in this package also can be given with an un‐\nderscore rather than a hyphen (e.g. --dryrun).\n", "flag": "-d", "long": "--dry-run" }, { "name": "-e --enumerate", "content": "some utilities (e.g. sgses and sgvpd) store a lot of information in internal tables.\nThis option will output that information in some readable form (e.g. sorted by an\nacronym or by page number) then exit. Note that with this option DEVICE is ignored (as\nare most other options) and no SCSI IO takes place, so the invoker does not need any\nelevated permissions.\n", "flag": "-e", "long": "--enumerate" }, { "name": "-h -? --help", "content": "output the usage message then exit. In a few older utilities the '-h' option requests\nhexadecimal output. In these cases the '-?' option will output the usage message then\nexit.\n", "flag": "-?", "long": "--help" }, { "name": "-H --hex", "content": "for SCSI commands that yield a non-trivial response, print out that response in ASCII\nhexadecimal. To produce hexadecimal that can be parsed by other utilities (e.g. with‐\nout a relative address to the left and without trailing ASCII) use this option three\nor four times.\n", "flag": "-H", "long": "--hex" }, { "name": "-i --in", "content": "many SCSI commands fetch a significant amount of data (returned in the data-in buffer)\nwhich several of these utilities decode (e.g. sgvpd and sglogs). To separate the two\nsteps of fetching the data from a SCSI device and then decoding it, this option has\nbeen added. The first step (fetching the data) can be done using the --hex or --raw\noption and redirecting the command line output to a file (often done with \">\" in Unix\nbased operating systems). The difference between --hex and --raw is that the former\nproduces output in ASCII hexadecimal while --raw produces its output in \"raw\" binary.\nThe second step (i.e. decoding the SCSI response data now held in a file) can be done\nusing this --in=FN option where the file name is FN. If \"-\" is used for FN then stdin\nis assumed, again this allows for command line redirection (or piping). That file (or\nstdin) is assumed to contain ASCII hexadecimal unless the --raw option is also given\nin which case it is assumed to be binary. Notice that the meaning of the --raw option\nis \"flipped\" when used with --in=FN to act on the input, typically it acts on the out‐\nput data.\nSince the structure of the data returned by SCSI commands varies considerably then the\nusage information or the manpage of the utility being used should be checked. In some\ncases --hex may need to be used multiple times (and is more conveniently given as\n'-HH' or '-HHH).\n", "flag": "-i", "long": "--in" }, { "name": "-i --inhex", "content": "This option has the same or similar functionality as --in=FN. And perhaps 'inhex' is\nmore descriptive since by default, ASCII hexadecimal is expected in the contents of\nfile: FN. Alternatively the short form option may be -I or -X. See the \"FORMAT OF\nFILES CONTAINING ASCII HEX\" section below for more information.\n", "flag": "-i", "long": "--inhex" }, { "name": "-m --maxlen", "content": "several important SCSI commands (e.g. INQUIRY and MODE SENSE) have response lengths\nthat vary depending on many factors, only some of which these utilities take into ac‐\ncount. The maximum response length is typically specified in the 'allocation length'\nfield of the cdb. In the absence of this option, several utilities use a default allo‐\ncation length (sometimes recommended in the SCSI draft standards) or a \"double fetch\"\nstrategy. See sglogs(8) for its description of a \"double fetch\" strategy. These\ntechniques are imperfect and in the presence of faulty SCSI targets can cause problems\n(e.g. some USB mass storage devices freeze if they receive an INQUIRY allocation\nlength other than 36). Also use of this option disables any \"double fetch\" strategy\nthat may have otherwise been used.\n", "flag": "-m", "long": "--maxlen" }, { "name": "-r --raw", "content": "for SCSI commands that yield a non-trivial response, output that response in binary to\nstdout. If any error messages or warning are produced they are usually sent to stderr\nso as to not interfere with the output from this option.\nSome utilities that consume data to send to the DEVICE along with the SCSI command,\nuse this option. Alternatively the --in=FN option causes DEVICE to be ignored and the\nresponse data (to be decoded) fetched from a file named FN. In these cases this option\nmay indicate that binary data can be read from stdin or from a nominated file (e.g.\nFN).\n", "flag": "-r", "long": "--raw" }, { "name": "-t --timeout", "content": "utilities that issue potentially long-running SCSI commands often have a --time‐\nout=SECS option. This typically instructs the operating system to abort the SCSI com‐\nmand in question once the timeout expires. Aborting SCSI commands is typically a messy\nbusiness and in the case of format like commands may leave the device in a \"format\ncorrupt\" state requiring another long-running re-initialization command to be sent.\nThe argument, SECS, is usually in seconds and the short form of the option may be\nsomething other than -t since the timeout option was typically added later as storage\ndevices grew in size and initialization commands took longer. Since many utilities had\nrelatively long internal command timeouts before this option was introduced, the ac‐\ntual command timeout given to the operating systems is the higher of the internal\ntimeout and SECS.\nMany long running SCSI commands have an IMMED bit which causes the command to finish\nrelatively quickly but the initialization process to continue. In such cases the RE‐\nQUEST SENSE command can be used to monitor progress with its progress indication field\n(see the sgrequests and sgturs utilities). Utilities that send such SCSI command\neither have an --immed option or a --wait option which is the logical inverse of the\n\"immediate\" action.\n", "flag": "-t", "long": "--timeout" }, { "name": "-v --verbose", "content": "increase the level of verbosity, (i.e. debug output). Can be used multiple times to\nfurther increase verbosity. The additional output caused by this option is almost al‐\nways sent to stderr.\n", "flag": "-v", "long": "--verbose" }, { "name": "-V --version", "content": "print the version string and then exit. Each utility has its own version number and\ndate of last code change.\n", "flag": "-V", "long": "--version" } ] }, "NUMERIC ARGUMENTS": { "content": "Many utilities have command line options that take numeric arguments. These numeric arguments\ncan be large values (e.g. a logical block address (LBA) on a disk) and can be inconvenient to\nenter in the default decimal representation. So various other representations are permitted.\n\nMultiplicative suffixes are accepted. They are one, two or three letter strings appended di‐\nrectly after the number to which they apply:\n\nc C *1\nw W *2\nb B *512\nk K KiB *1024\nKB kB *1000\nm M MiB *1048576\nMB mB *1000000\ng G GiB *(2^30)\nGB gB *(10^9)\nt T TiB *(2^40)\nTB *(10^12)\np P PiB *(2^50)\nPB *(10^15)\n\nAn example is \"2k\" for 2048. The large tera and peta suffixes are only available for numeric\narguments that might require 64 bits to represent internally.\n\nThese multiplicative suffixes are compatible with GNU's dd command (since 2002) which claims\ncompliance with SI and with IEC 60027-2.\n\nA suffix of the form \"x\" multiplies the preceding number by . An example is \"2x33\" for\n\"66\". The left argument cannot be '0' as '0x' will be interpreted as hexadecimal number pre‐\nfix (see below). The left argument to the multiplication must end in a hexadecimal digit\n(i.e. 0 to f) and the whole expression cannot have any embedded whitespace (e.g. spaces).\nAn ugly example: \"0xfx0x2\" for 30.\n\nA suffix of the form \"+\" adds the preceding number to . An example is \"3+1k\" for\n\"1027\". The left argument to the addition must end in a hexadecimal digit (i.e. 0 to f) and\nthe whole expression cannot have any embedded whitespace (e.g. spaces). Another example:\n\"0xf+0x2\" for 17.\n\nAlternatively numerical arguments can be given in hexadecimal. There are two syntaxes. The\nnumber can be preceded by either \"0x\" or \"0X\" as found in the C programming language. The\nsecond hexadecimal representation is a trailing \"h\" or \"H\" as found in (storage) standards.\nWhen hex numbers are given, multipliers cannot be used. For example the decimal value \"256\"\ncan be given as \"0x100\" or \"100h\".\n", "subsections": [] }, "FORMAT OF FILES CONTAINING ASCII HEX": { "content": "Such a file is assumed to contain a sequence of one or two digit ASCII hexadecimal values\nseparated by whitespace. \"Whitespace consists of either spaces, tabs, blank lines, or any\ncombination thereof\". Each one or two digit ASCII hex pair is decoded into a byte (i.e. 8\nbits). The following will be decoded to valid (ascending valued) bytes: '0', '01', '3', 'c',\n'F', '4a', 'cC', 'ff'. Lines containing only whitespace are ignored. The contents of any\nline containing a hash mark ('#') is ignored from that point until the end of that line.\nUsers are encouraged to use hash marks to introduce comments in hex files. The author uses\nthe extension'.hex' on such files. Examples can be found in the 'inhex' directory.\n", "subsections": [] }, "MICROCODE AND FIRMWARE": { "content": "There are two standardized methods for downloading microcode (i.e. device firmware) to a SCSI\ndevice. The more general way is with the SCSI WRITE BUFFER command, see the sgwritebuffer\nutility. SCSI enclosures have their own method based on the Download microcode control/status\ndiagnostic page, see the sgsesmicrocode utility.\n", "subsections": [ { "name": "SCRIPTS, EXAMPLES and UTILS", "content": "There are several bash shell scripts in the 'scripts' subdirectory that invoke compiled util‐\nities (e.g. sgreadcap). Several of the scripts start with 'scsi' rather than 'sg'. One\npurpose of these scripts is to call the same utility (e.g. sgreadcap) on multiple devices.\nMost of the basic compiled utilities only allow one device as an argument. Some distributions\ninstall these scripts in a more visible directory (e.g. /usr/bin). Some of these scripts have\nman page entries. See the README file in the 'scripts' subdirectory.\n\nThere is some example C code plus examples of complex invocations in the 'examples' subdirec‐\ntory. There is also a README file. The example C may be a simpler example of how to use a\nSCSI pass-through in Linux than the main utilities (found in the 'src' subdirectory). This is\ndue to the fewer abstraction layers (e.g. they don't worry the MinGW in Windows may open a\nfile in text rather than binary mode).\n\nSome utilities that the author has found useful have been placed in the 'utils' subdirectory.\n" } ] }, "WEB SITE": { "content": "There is a web page discussing this package at http://sg.danny.cz/sg/sg3utils.html . The de‐\nvice naming used by this package on various operating systems is discussed at:\nhttp://sg.danny.cz/sg/devicename.html . There is a git code mirror at\nhttps://github.com/hreinecke/sg3utils . The principle code repository uses subversion and is\non the author's equipment. The author keeps track of this via the subversion revision number\nwhich is an ascending integer (currently at 774 for this package). The github mirror gets up‐\ndated periodically from the author's repository. Depending on the time of update, the above\nDownloads section at sg.danny.cz may be more up to date than the github mirror.\n", "subsections": [] }, "AUTHORS": { "content": "Written by Douglas Gilbert. Some utilities have been contributed, see the CREDITS file and\nindividual source files (in the 'src' directory).\n", "subsections": [] }, "REPORTING BUGS": { "content": "Report bugs to .\n", "subsections": [] }, "COPYRIGHT": { "content": "Copyright © 1999-2021 Douglas Gilbert\nSome utilities are distributed under a GPL version 2 license while others, usually more re‐\ncent ones, are under a FreeBSD license. The files that are common to almost all utilities and\nthus contain the most reusable code, namely sglib.[hc], sgcmdsbasic.[hc] and sgcmdsex‐\ntra.[hc] are under a FreeBSD license. There is NO warranty; not even for MERCHANTABILITY or\nFITNESS FOR A PARTICULAR PURPOSE.\n", "subsections": [] }, "SEE ALSO": { "content": "", "subsections": [ { "name": "sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1)", "content": "sg3utils-1.46 March 2021 SG3UTILS(8)" } ] } } } }