title: sg3_utils(8)

text:
# sg3_utils(8)

## NAME
sg3_utils - a package of utilities for sending SCSI commands

## SYNOPSIS
sg_* [--dry-run] [--enumerate] [--help] [--hex] [--in=FN] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--raw] [--timeout=SECS] [--verbose] [--version] [OTHER_OPTIONS] [DEVICE]

## DESCRIPTION
sg3_utils is a package of utilities that send SCSI commands to the given DEVICE via a SCSI pass through interface provided by the host operating system.

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 DEVICE.

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.

SCSI draft standards can be found at https://www.t10.org . The standards themselves can be purchased from ANSI and other standards organizations. A good overview of various SCSI standards can be seen in https://www.t10.org/scsi-3.htm with the SCSI command sets in the upper part of the diagram. The highest level (i.e. most abstract) document is the SCSI Architecture Model (SAM) with SAM-5 being the most recent standard (ANSI INCITS 515-2016) with the most recent draft being SAM-6 revision 4 . SCSI commands in common with all device types can be found in SCSI Primary Commands (SPC) of which SPC-5 is the most recent standard (ANSI INCITS 502-2020). The most recent SPC draft is SPC-6 revision 6. 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.

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 https://www.t10.org for more information.

There is some support for SCSI tape devices but not for their basic operation. The reader is referred to the "mt" utility.

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 DEVICE argument may appear after, between or prior to any options.

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).

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.

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.

## ENVIRONMENT VARIABLES
The SG3_UTILS_OLD_OPTS environment variable is explained in the previous section. It is only for backward compatibility of the command line options for older utilities.

The SG3_UTILS_INVOCATION environment variable has been implemented on some utilities that decode a lot of data. When SG3_UTILS_INVOCATION is set those utilities will print out a line of 60 "v" characters. After that the utility name and version (which includes a date) followed by a line by line breakdown of the command line arguments that the utility was invoked with. The command line arguments include the utility name and options in the order they were given. The output is sent to stdout. The option is designed to help automatic testing of utilities in the package.

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 device, to return SCSI sense in 'fixed' format. If this variable is non-zero then then the returned SCSI sense will be in 'descriptor' format.

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.

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).

## LINUX DEVICE NAMING
Most disk block devices have names like /dev/sda, /dev/sdb, /dev/sdc, etc. SCSI disks in Linux have always had names like that but in recent Linux kernels it has become more common for many other disks (including SATA disks and USB storage devices) to be named like that. Partitions within a disk are specified by a number appended to the device name, starting at 1 (e.g. /dev/sda1 ).

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.

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.

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.

Very little has changed in Linux device naming in the Linux kernel 3 and 4 series.

## WINDOWS DEVICE NAMING
Storage and related devices can have several device names in Windows. Probably the most common in the volume name (e.g. "D:"). There are also a "class" device names such as "PhysicalDrive<n>", "CDROM<n>" and "TAPE<n>". <n> is an integer starting at 0 allocated in ascending order as devices are discovered (and sometimes rediscovered).

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.

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.

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).

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.

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.

## FREEBSD DEVICE NAMING
SCSI disks have block names of the form /dev/da<num> where <num> is an integer starting at zero. The "da" is replaced by "sa" for SCSI tape drives and "cd" for SCSI CD/DVD/BD drives. Each SCSI device has a corresponding pass-through device name of the form /dev/pass<num> where <num> is an integer starting at zero. The "camcontrol devlist" command may be useful for finding out which SCSI device names are available and the correspondence between class and pass-through names.

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 "/".

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.

## SOLARIS DEVICE NAMING
SCSI device names below the /dev directory have a form like: c5t4d3s2 where the number following "c" is the controller (HBA) number, the number following "t" is the target number (from the SCSI parallel interface days) and the number following "d" is the LUN. Following the "s" is the slice number which is related to a partition and by convention "s2" is the whole disk.

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 .

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.

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.

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 .

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.

## NVME SUPPORT
NVMe (or NVM Express) is a relatively new storage transport and command set. The level of abstraction of the NVMe command set is somewhat lower the SCSI command sets, closer to the level of abstraction of ATA (and SATA) command sets. NVMe claims to be designed with flash and modern "solid state" storage in mind, something unheard of when SCSI was originally developed in the 1980s.

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.

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.

As a side effect of this "juggling" if the sg_inq utility is used (without the --page= option) on a NVMe DEVICE 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 DEVICE then parts of the NVMe Identify controller and namespace response are translated to a SCSI standard INQUIRY response which is then decoded and output.

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).

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).

## EXIT STATUS
To aid scripts that call these utilities, the exit status is set to indicate success (0) or failure (1 or more). Note that some of the lower values correspond to the SCSI sense key values.

The exit status values listed below can be given to the sg_decode_sense utility (which is found in this package) as follows:

sg_decode_sense --err=<exit_status>

and a short explanatory string will be output to stdout.

The exit status values are:

0

success. Also used for some utilities that wish to return a boolean value for the "true" case (and that no error has occurred). The false case is conveyed by exit status 36.

1

syntax error. Either illegal command line options, options with bad arguments or a combination of options that is not permitted.

2

the DEVICE reports that it is not ready for the operation requested. The DEVICE 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 DEVICE may be temporarily blocked while error recovery is taking place. See exit status values 12 and 13 below which refine this exit value.

3

the DEVICE 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.

5

the DEVICE 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.

6

the DEVICE 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.

7

the DEVICE reports a "data protect" sense key. This implies some mechanism has blocked writes (or possibly all access to the media).

9

the DEVICE reports an illegal request with an additional sense code of "invalid command operation code" which means that it doesn't support the requested command.

10

the DEVICE 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.

11

the DEVICE reports an aborted command. In some cases aborted commands can be retried immediately (e.g. if the transport aborted the command due to congestion).

12

the DEVICE reports a sense key of not ready together with an additional sense code of "target port in standby state".

13

the DEVICE reports a sense key of not ready together with an additional sense code of "target port in unavailable state".

14

the DEVICE reports a miscompare sense key. VERIFY and COMPARE AND WRITE commands may report this.

15

the utility is unable to open, close or use the given DEVICE 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.

17

a SCSI "Illegal request" sense code received with a flag indicating the Info field is valid. This is often a LBA but its meaning is command specific.

18

the DEVICE 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.

19

the DEVICE reports an illegal request with an additional sense code of "invalid field in parameter list". The parameter list is extra data sent to the DEVICE for some commands (e.g. FORMAT UNIT)

20

the DEVICE 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.

21

the DEVICE 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 .

22

the DEVICE 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 DEVICE is returned. Since LBAs are origin zero they range from 0 to n-1 where n is the number of blocks on the DEVICE, so the LBA of the last block is one less than the total number of blocks.

24

the DEVICE reports a SCSI status of "reservation conflict". This means access to the DEVICE with the current command has been blocked because another machine (HBA or SCSI "initiator") holds a reservation on this DEVICE. On modern SCSI systems this is related to the use of the PERSISTENT RESERVATION family of commands.

25

the DEVICE reports a SCSI status of "condition met". Currently only the PRE-FETCH command (see SBC-4) yields this status.

26

the DEVICE 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.

27

the DEVICE reports a SCSI status of "task set full".

28

the DEVICE reports a SCSI status of "ACA active". ACA is "auto contingent allegiance" and is seldom used.

29

the DEVICE 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".

31

error involving two or more command line options. They may be contradicting, select an unsupported mode, or a required option (given the context) is missing.

32

there is a logic error in the utility. It corresponds to code comments like "shouldn't/can't get here". Perhaps the author should be informed.

33

the command sent to DEVICE has timed out.

34

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).

35

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 from a READ command.

36

no error has occurred plus the utility wants to convey a boolean value of false. The corresponding true value is conveyed by a 0 exit status.

40

the command sent to DEVICE 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.

41

the command sent to DEVICE 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.

47

flock (Unix system call) error.

48

this is an internal message indicating a NVMe status field (SF) is other than zero after a command has been executed (i.e. something went wrong). Work in this area is currently experimental.

49

low level driver reports a response's residual count (i.e. number of bytes actually received by HBA is 'requested_bytes - residual_count') that is nonsensical.

50

OS system calls that fail often return a small integer number to help. In Unix these are called "errno" values where 0 implies no error. These error codes set aside 51 to 96 for mapping these errno values but that may not be sufficient. Higher errno values that cannot be mapped are all mapped to this value (i.e. 50).

Note that an errno value of 0 is mapped to error code 0.

50 + <os_error_number>

OS system calls that fail often return a small integer number to help indicate what the error is. For example in Unix the inability of a system call to allocate memory returns (in 'errno') ENOMEM which often is associated with the integer 12. So 62 (i.e. '50 + 12') may be returned by a utility in this case. It is also possible that a utility in this package reports 50+ENOMEM when it can't allocate memory, not necessarily from an OS system call. In recent versions of Linux the file showing the mapping between symbolic constants (e.g. ENOMEM) and the corresponding integer is in the kernel source code file: include/uapi/asm-generic/errno-base.h

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.

97

a SCSI command response failed sanity checks.

98

the DEVICE reports it has a check condition but the error doesn't fit into any of the above categories.

99

any errors that can't be categorized into values 1 to 98 may yield this value. This includes transport and operating system errors after the command has been sent to the device.

100-125

these error codes are used by the ddpt utility which uses the sg3_utils library. They are mainly specialized error codes associated with offloaded copies.

126

the utility was found but could not be executed. That might occur if the executable does not have execute permissions.

127

This is the exit status for utility not found. That might occur when a script calls a utility in this package but the PATH environment variable has not been properly set up, so the script cannot find the executable.

128 + <signum>

If a signal kills a utility then the exit status is 128 plus the signal number. For example if a segmentation fault occurs then a utility is typically killed by SIGSEGV which according to 'man 7 signal' has an associated signal number of 11; so the exit status will be 139 .

255

the utility tried to yield an exit status of 255 or larger. That should not happen; given here for completeness.

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.

## COMMON OPTIONS
Arguments to long options are mandatory for short options as well. In the short form an argument to an option uses zero or more spaces as a separator (i.e. the short form does not use "=" as a separator).

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).

Some options are used uniformly in most of the utilities in this package. Those options are listed below. Note that there are some exceptions.

-d, --dry-run

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 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 --dry-run option 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 underscore rather than a hyphen (e.g. --dry_run).

-e, --enumerate

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 DEVICE is ignored (as are most other options) and no SCSI IO takes place, so the invoker does not need any elevated permissions.

-h, -?, --help

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.

-H, --hex

for SCSI commands that yield a non-trivial response, print out that response as a series ASCII hexadecimal bytes. When used once, 16 bytes are printed on each line, prefixed by a relative address, starting at 0 (hex). When used twice, an ASCII rendering of the 16 bytes is appended to each line, with non-printable characters replaced by a '.' . When used three times only the 16 hex bytes are printed on each line (hence no address prefix nor ASCII appended). To produce hexadecimal that can be parsed by other utilities use this option three, four or five times.

The use of this option, especially when used multiple times has evolved over time as it has become more useful (at least in testing and fixing bugs). So check this option's description in the manpage of the utility being used. An example of a corner case with the '-HHH' option is with the sg_inq utility and the ATA Information VPD page. The sg_inq utility does not decode the ATA IDENTIFY DEVICE command response but instead outputs hexadecimal 16 bit words (little endian) suitable for the hdparm utility to decode.

-i, --in=FN

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 --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 output 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).

-i, --inhex=FN

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 "HEX, BINARY AND JSON FORMATS" section below for more information.

--json[=JO]

The default output of most utilities that decode information returned from SCSI devices is designed for human readability. Sometimes a more parseable form of output is required and JSON is a popular way to do this. Only utilities that decode a significant amount of SCSI data support this option.

The corresponding short option is usually -j[JO] but maybe -J[JO] if -j is already in use. Note that in all cases JO argument is itself optional. See the sg3_utils_json manpage for more information.

-J, --js-file=JFN

output is in JSON format and it is sent to a file named JFN. If that file exists then it is truncated. By default, the JSON output is sent to stdout.

When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values.

-m, --maxlen=LEN

several important SCSI commands (e.g. INQUIRY and MODE SENSE) have response lengths that vary depending on many factors, only some of which these utilities take into account. The maximum response length is typically specified in the 'allocation length' field of the cdb. In the absence of this option, several utilities use a default allocation length (sometimes recommended in the SCSI draft standards) or a "double fetch" strategy. See sg_logs(8) for its description of a "double fetch" strategy. These techniques are imperfect and in the presence of faulty SCSI targets can cause problems (e.g. some USB mass storage devices freeze if they receive an INQUIRY allocation length other than 36). Also use of this option disables any "double fetch" strategy that may have otherwise been used.

To head off a class of degenerate bugs, if LEN 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.

-r, --raw

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).

-t, --timeout=SECS

utilities that issue potentially long-running SCSI commands often have a --timeout=SECS 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, 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 actual 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 in the CDB which causes the command to return relatively quickly but the requested operation has only been commenced, not completed. In such cases the REQUEST SENSE command can be used to monitor progress via its progress indication field (see the sg_requests and sg_turs utilities). Utilities that send such SCSI commands either have an --immed option or a --wait option which is the logical inverse of the "immediate" action. Sending a SCSI data access command to a device which is busy performing a long running SCSI command (in background) will typically receive a NOT READY sense key with an additional sense code of 0x04 and a qualifier code which indicates which long running operation the device is performing.

An alternate long option form is --tmo=SECS.

-v, --verbose

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.

-V, --version

print the version string and then exit. Each utility has its own version number and date of last code change.

## NUMERIC ARGUMENTS
Many utilities have command line options that take numeric arguments. These numeric arguments can be large values (e.g. a logical block address (LBA) on a disk) and can be inconvenient to enter in the default decimal representation. So various other representations are permitted.

Multiplicative suffixes are accepted. They are one, two or three letter strings appended directly after the number to which they apply:

c C *1

w W *2

b B *512

k K KiB *1024

KB kB *1000

m M MiB *1048576

MB mB *1000000

g G GiB *(2^30)

GB gB *(10^9)

t T TiB *(2^40)

TB *(10^12)

p P PiB *(2^50)

PB *(10^15)

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.

These multiplicative suffixes are compatible with GNU's dd command (since 2002) which claims compliance with SI and with IEC 60027-2.

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.

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.

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".

## HEX, BINARY AND JSON FORMATS
Both hexadecimal (ASCII) and binary can be used as low level output of SCSI responses that can be redirected to a file and decoded with a later invocation. JSON output is typically generated after decoding and considered a high level output that may be parsed by some other tool. No utilities in sg3_utils can parse JSON as input.

JSON output is outlined in its own manpage, see: sg3_utils_json(8).

Binary and especially hexadecimal output can have two roles: for viewing immediately (e.g. when debugging) or as a parsable output that can be decoded later. The latter action uses the --inhex=FN option. For viewing hexadecimal output (e.g. from a SCSI command response) the --hex option can be used once or twice. Both have output similar to:

$ hexdump --no-squeezing -C

When there is a single --hex option, the ASCII rendering to the right of each line is not shown; when used twice the ASCII rendering is shown.

When the --hex option is used three or more times then the assumption is that it will be parsed later. Only hex data bytes are output, up to 16 per line. This is close to this hexdump invocation:

$ hexdump --no-squeezing -C | cut -s -d ' ' -f 2-19

This should remove the first column (i.e. the count) and remove the ASCII rendering to the right. This makes parsing the hexadecimal a lot easier. When used 4 or more times the --hex options adds comments (i.e. lines starting with the hash symbol):

$ sg_logs -HHHH -A /dev/sdc

\# Supported log pages log page [0x0]:

00 00 00 03 00 0d 2f

\# Supported log pages and subpages log page [0x0, 0xff]:

40 ff 00 0e 00 00 00 ff 0d 00 0d 01 0d ff 2f 00

2f ff

...

Comments can also be placed after hex in a line, everything from the '#' to the end of a line is ignored.

There are many examples of hex files suitable for the --inhex=FN option in the 'inhex' directory. The naming of files in that directory is the name of the utility that will decode it with the "sg_" prefix removed and a ".hex" suffix added. Those hex files can be viewed with a text editor and most contain an example of invoking it in the leading comments.

The hexadecimal format can be converted into binary using the sg_decode_sense utility with these options: "--inhex=HFN --nodecode --write=WFN". The input (in hex) is in the HFN file while the output is placed in the WFN file.

To convert a binary file into a hexadecimal form that can be given as input to various sg3_utils utilities, the sg_decode_sense utility can also be used with these options: "--binary=BFN --nodecode -HHH" and the hex output will be sent to the console (stdout).

## MICROCODE AND FIRMWARE
There are two standardized methods for downloading microcode (i.e. device firmware) to a SCSI device. The more general way is with the SCSI WRITE BUFFER command, see the sg_write_buffer utility. SCSI enclosures have their own method based on the Download microcode control/status diagnostic page, see the sg_ses_microcode utility.

## SCRIPTS, EXAMPLES and UTILS
There are several bash shell scripts in the 'scripts' subdirectory that invoke compiled utilities (e.g. sg_readcap). Several of the scripts start with 'scsi_' rather than 'sg_'. One purpose of these scripts is to call the same utility (e.g. sg_readcap) on multiple devices. Most of the basic compiled utilities only allow one device as an argument. Some distributions install these scripts in a more visible directory (e.g. /usr/bin). Some of these scripts have man page entries. See the README file in the 'scripts' subdirectory.

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).

Some utilities that the author has found useful have been placed in the 'utils' subdirectory.

## DEBUGGING
Each utility and most scripts have a --verbose option (short form: -v) that can be used multiple times to increase the verbosity of the output to aid debugging. Normal output (if any) is sent to stdout while verbose output (and error output) is sent to stderr. This may be important when the (normal output) of a utility is being piped to another command (e.g. the grep command to find a particular field in the output).

The Linux SCSI subsystem has a pseudo file for getting and changing the SCSI logging level: /proc/sys/dev/scsi/logging_level . The scsi_logging_level script in this package can be used to manipulate the logging level in a command line friendly way. See its manpage.

The logging level runs from 0 (no logging and the default) to 7 (lots of logging) and applies to all storage devices that use the SCSI subsystem. The logging output goes to "the log" which is often the /var/log/syslog file.

The Linux SCSI generic (sg) driver is often used under the utilities in this package. It uses a seldom (otherwise) used logging type of SCSI_LOG_TIMEOUT. An example of its use to turn on full debugging is:

scsi_logging_level -s -T 7

To reduce the amount of output to only error paths, the following is suggested:

scsi_logging_level -s -T 3

And to turn off logging in the sg driver:

scsi_logging_level -s -T 0

For analyzing machine crashes associated with a SCSI command, nothing beats a real serial port. By "real" means that it is _not_ a USB serial port. The reason is that like SCSI, USB needs a functioning software stack within the OS kernel, the very thing that may be crippled during a machine crash.

Modern laptops do not have real serial ports and many server machines don't either (or it is an optional extra). In Linux the netconsole module does a pretty good job by sending log entries to another machine (on the same sub-net)) using the UDP ("fire and forget") network protocol .

## WEB SITE
There is a web page discussing this package at https://sg.danny.cz/sg/sg3_utils.html . The device naming used by this package on various operating systems is discussed at: https://sg.danny.cz/sg/device_name.html . There is a git code mirror at https://github.com/hreinecke/sg3_utils . The principle code repository uses subversion and is on the author's equipment. The author keeps track of this via the subversion revision number which is an ascending integer (currently at 922 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.

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

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 1999-2023 Douglas Gilbert

Some utilities are distributed under a GPL version 2 license while others, usually more recent ones, are under a BSD-2-Clause 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 BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg3_utils_json,sg_decode_sense(sg3_utils), sdparm(sdparm), ddpt(ddpt), lsscsi(lsscsi), dmesg(1), mt(1), hdparm(hdparm), hexdump(util-linux)

The format of this section is: <utility_name>(<package_containing_utility>) or <utility_name>(<manpage_section_number_containing_utility>) .


title: sg3_utils_json(8)

text:
# sg3_utils_json(8)

## NAME
sg3_utils_json - JSON output for some sg3_utils utilities

## SYNOPSIS
sg_* --json[=JO] [--js-file=JFN] [OTHER_OPTIONS] [DEVICE]

## DESCRIPTION
sg3_utils is a package of utilities that send SCSI commands to the given DEVICE via a SCSI pass through interface provided by the host operating system. Some utilities, mainly those decoding structured data returned by SCSI commands (e.g. sg_vpd) can optionally provide JSON output, rather than simple, plain text output. The default remains plain text output.

JavaScript Object Notation (JSON) is an open standard file format that can be used for data exchange between programs including across a network. See https://en.wikipedia.org/wiki/JSON . JSON comes in many flavours and this one uses the json-builder C implementation found at https://github.com/json-parser/json-builder which implements four simple JSON data types: string, integer, boolean and null. Its other data types are JSON object and JSON array.

This project uses the 'snake_case' convention for JSON object names: all in lower case letters or numerals with individual words joined with a single underscore (e.g. "starting_lba"). There should be no leading or trailing underscore characters. The json-builder library uses the SPDX-License-Identifier: BSD-2-Clause which is the same license as the bulk of the utilities in the sg3_utils package.

The json-builder library is relatively lightweight (700 lines of C code) and is 'hidden' fully within the sg3_utils library so that its function interface and data types are not available (directly) to the utilities in the sg3_utils package. That is why the json-builder interface (a file named sg_json_builder.h) is in the lib directory and not in the include directory. As presented on github, json-builder shares some header files with its companion json-parser. The author has modified the json-builder header to include what is needed from the json-parser header so that only the builder and not the parser are built. The parser could be added later, but currently there seems to be no need for it.

The user interface to JSON functionality in the sg3_utils package is heavily based on what has been done by Christian Franke and others in smartctl, a utility in the smartmontools package for getting S.M.A.R.T. information from disks (and other storage devices).

This manpage discusses the --json[=JO] and --js-file=JFN command line options. Notice that the argument to --json is itself optional. In its shorter form the --json option may either be -j or -J (lower case preferred if not already in use). The shorter form may also take an argument but an "=" must precede the JO argument with no spaces either side of the "=".

Some care has been taken with quotes in this manpage. Double quotes are used around JSON object names, single quotes are used for all other purposes.

## ENVIRONMENT VARIABLES
The SG3_UTILS_JSON_OPTS environment variable allows the user to override the default values of the JO settings. Those settings can again be overridden by the command line --json[=JO] option. If the string associated with SG3_UTILS_JSON_OPTS cannot be parsed this error message is sent to stderr: 'error parsing SG3_UTILS_JSON_OPTS environment variable, ignore'.

## OPTIONS
Since the argument to --json[=JO] is optional, in the shorter form there can be no space(s) between the option and its argument.

-j[=JO], --json[=JO]

JO is a string of zero or more characters whose order is not significant apart from the negation characters ('-' is preferred). The negation character must appear immediately before the (boolean) feature it is toggling.

In the short form the option letter may be other than -j if that letter has already been used (-J is preferred next). For example the sg_ses utility uses -j for its 'join' operation. Also since the argument to the short form option is itself optional, there can be no spaces between the short form option, the "=", and JO, if it is given. Some short form examples: '-jl' requests JSON output (with no argument option) and whatever the '-l' short option means in the invoked utility; '-j=h' requests JSON output with some integers additional rendered as JSON strings of hex.

-J, --js-file=JFN

output is in JSON format and it is sent to a file named JFN. If that file exists then it is truncated. By default, the JSON output is sent to stdout.

When this option is given, the --json[=JO] option is implied and need not be given. The --json[=JO] option may still be needed to set the JO parameter to non-default values.

The short option may be other than -J if that short option was already in use.

## JSON CONTROL CHARACTERS
Each JO string is made up of zero or more of the following JSON control characters.

0

If pretty printing JSON output, tab to 2 spaces.

2

If pretty printing JSON output, tab to 2 spaces.

4

If pretty printing JSON output, tab to 4 spaces.

This is the default tab setting for pretty printing JSON.

8

If pretty printing JSON output, tab to 8 spaces.

-

negation character. Toggles the (boolean) sense of the following control character.

e

this is a boolean control character for "exit status". If active an "exit status" field is placed at the end of the JSON output. The integer value of this field is the Unix exit status value that is return to the operating system when this utility exits. The value of 0 is a good exit (i.e. no errors detected).

This boolean control character is default on (true).

h

this is a boolean control character for 'hexadecimal'. Many values associated with SCSI are best (or at least historically) viewed in hexadecimal while JSON output prefers decimal integers (assumed to have a maximum size of 64 bits, signed). The maximum size of most SCSI fields is 64 bit _unsigned_ . Also some SCSI fields are masks which are best viewed in hex. When this control character is active most (non-trivial) fields that have an integer value instead receive a a sub-object containing at least a "i" field with the integer value and a "hex" field with the corresponding hex value in a JSON string. That hex string has no hex decorations (i.e. no leading '0x' nor trailing 'h').

This boolean control character is default off (false).

k

this is a boolean control character for finer control of non-pretty printed JSON output. If the 'p' control character is set on (true) then this option has no effect.

If the 'p' control character is set off (false) and this control character is set off (false) then the single line JSON output contains some spaces for readability. If the 'p' control character is set off (false) and this control character is set on (true) then the JSON single line JSON output is 'packed' removing all unnecessary spaces.

This boolean control character is default off (false).

l

this is a boolean control character to control whether lead-in fields are output. Lead-in fields are at the start of the JSON output and include "json_format_version" and "utility_invoked" sub-objects. The "utility_invoked" sub-object includes "name", "version_date" string fields and an JSON array named "argv" with an entry for each command line argument. If the o control character is also active, then if available, the non_JSON output (i.e. the original, 'plain text' form) is placed in an array called "plain_text_output" with one element per line of 'normal' output.

This boolean control character is default on (true).

n

this is a boolean control character for "name_extra". It is used to provide additional information about the name it is a sub-object of. The most common usage is to spell out an abbreviated name (e.g. a T10 name like 'SKSV' to 'Sense Key Specific Valid'). Another use is to note that a T10 field is obsolete and in which T10 standard it first became obsolete. Also if the named field's value is a physical quantity where the unit is unclear (e.g. a timeout) then "name_extra" can state that (e.g. 'unit: millisecond'). Only some fields have associated "name_extra" data.

This boolean control character is default off (false).

o

this is a boolean control character to control whether normal (i.e. non-JSON) lines of output are placed in a JSON array (one element per line of normal output) within the utility_invoked subject (see control character l). The name of the array is "plain_text_output". This control character is active even if the lead-in fields control character (l) is negated.

This boolean control character is default off (false).

p

this boolean control character controls whether the JSON output is 'pretty printed' or sent in a relatively compact stream suitable for more efficient transmission over a communications channel.

The pretty printed form of output has one JSON name with its associated integer, string or boolean value per line; and one array element per line. JSON objects and arrays that have an associated JSON object as their value, have their name on a separate line. These lines are indented with the current tab setting to indicate the level of nesting. Basically the pretty printed form is for human consumption.

There are two forms of non-pretty printed output, see the 'packed' control character ['k'].

This boolean control character is default on (true).

s

this boolean control character controls whether T10 field values that have a defined meaning are broken out with an added JSON sub-object usually named "meaning". When active the field name has a sub-object that contains at least an "i" field with the integer value of the field and a JSON string object, usually named "meaning", with a string that corresponds to the T10 defined meaning of the value in the "i" field.

This boolean control character is default on (true).

v

this is an integer control character that controls the amount of debug output. It can be given multiple times to increase the level of JSON debug verbosity in the output.

Note that this verbose control character is JSON specific while the --verbose option (short form: fI-v often repeated: fI-vvv) that most utilities support is more general.

This integer control character is set to 0 by default.

## OUTPUT PROCESSING
The default remains the same for all utilities that support the --json option, namely the decoded information is sent to stdout in plain text form. Errors are reported to stderr and may cause the early termination of a utility (e.g. command line option syntax error).

When the --json option is given and no errors are detected, then only JSON is normally sent to stdout. As the SCSI response is parsed, a JSON representation is built as a tree in memory. After all other actions (perhaps apart from the final exit status report) that JSON tree is 'dumped' to stdout. This means if there is any non-JSON output sent to stdout that it will appear _before_ the JSON output.

If the 'o' control character is in the JO argument to the --json option, then the former plain text output is placed in a JSON array named "plain_text_output" within a JSON object named "utility_invoked".

Each line of the former 'plain text' output is placed in its own element of the JSON array.

A JSON tree is built in memory as the utility parses the data returned from the SCSI device (e.g. sg_vpd parsing a VPD page returned from a SCSI INQUIRY command). SCSI 'list's become JSON named arrays (e.g. in the Device Identification VPD page there is a 'Designation descriptor list' that becomes a JSON array named "designation_descriptor_list").

At the completion of the utility that JSON tree is 'measured' taking into account the form of output (i.e. pretty-printed, single line or packed single line). For the pretty-printed JSON output, the size of each indentation in spaces is also given (i.e. the tab width). The JSON is then output to a single C string, then sent to stdout. If a NULL character (ASCII zero and C string terminator) somehow finds its way into a field that should (according to the spec) be space padded, then the JSON output may appear truncated.

Note that this JSON processing means that if a utility is aborted for whatever reason then no JSON output will appear. With the normal, plain text output processing, some output may appear before the utility aborts in such bad situations.

## BOOLEAN OR 0/1
In general, the JSON generated by this package outputs 1 bit SCSI fields as the integer value 0 (for false) and 1 (for true). This follows the SCSI convention which predates the common use of boolean. Also SCSI reserved fields are output as the integer value 0. Extensions to SCSI commands and associated data descriptors typically use parts of commands or data descriptors that were previously reserved.

## INTERACTION WITH OTHER OPTIONS
As stated above, the default output is in plain text form using 7 bit ASCII. The --json[=JO] option is designed to be an alternative to that plain text form. There are other alternative output formats such as the response output as a hexadecimal sequence of bytes or in 'raw' binary output; both of those take precedence over the --json[=JO] option. Other specialized output format (e.g. 'sg_inq --export') will usually take precedence over JSON output.

When the --raw option is used together with the --inhex=FN option only the data input to the utility is interpreted as binary. So the output format defaults to plain text form and thus can be changed to JSON if the --json[=JO] option is also used.

There is typically only one form of JSON output so options like --brief and --quiet are ignored in the JSON output. In some cases (i.e 'sg_inq --descriptors') the JSON output is expanded.

## ERRORS
No attempts have been made to translate errors into JSON form, apart from the final "exit_status" JSON object where a value of 0 means 'no errors'. Exit status values indicating a problem range from 1 to 255.

The sg_decode_sense utility will parse SCSI sense data into JSON form if requested. So if another utility is failing with a sense data report (most often seen when the --verbose option is used). That sense data (in hex bytes) could be cut-and-pasted onto the command line following 'sg_decode_sense -j ' which should then render that sense data in JSON.

Otherwise, when a error is detected while JSON output is selected, the error message is sent to stderr in plain text form. Typically once an error is detected the utility will exit, first dumping the JSON in-memory tree as discussed above and a non-zero exit status will be set. The JSON output will be well formed but missing any fields or list elements following the point that the error was detected.

The summary is that when JSON output is selected and an error occurs each utility will process the error the same way as it would if JSON output had not been selected. In most cases error messages, in plain text form, are sent to stderr.

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

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2022-2023 Douglas Gilbert

This software is distributed under the GPL version 2 or the BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg3_utils(sg3_utils), smartctl(smartmontools)


title: sg_bg_ctl(8)

summary: send SCSI BACKGROUND CONTROL command

text:
# sg_bg_ctl(8)

## NAME
sg_bg_ctl - send SCSI BACKGROUND CONTROL command

## SYNOPSIS
sg_bg_ctl [--ctl=CTL] [--help] [--time=TN] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI BACKGROUND CONTROL command to the DEVICE. This command was first found in the SBC-4 draft standard revision 8 (sbc4r08.pdf). It can be used to start and stop 'advanced background operations' on the DEVICE. Only resource or thin provisioned devices (logical units which are typically (solid state) disks) support this command. Those advanced background operations often include garbage collection type operations which may degrade the disk's performance while they are being performed.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-c, --ctl=CTL

CTL is the value placed in the BO_CTL field of the BACKGROUND CONTROL command (cdb). It is a two bit field so has 4 variants: 0 does not change the host initiated advanced background operations; 1 starts these operations; 2 stops these operations and 3 is reserved. The default value is 0.

-h, --help

output the usage message then exit.

-t, --time=TN

TN is a maximum time (with a unit of 100 ms or 1/10 second) that advanced background operations can occur. This value is ignored if the CTL argument is other than 1. The default value is 0 which means there is no maximum time limit. Only values 0 to 255 (which is 25.5 seconds) can be given. This value is place in the BO_TIME field of the BACKGROUND CONTROL command.

-v, --verbose

increase the level of verbosity, (i.e. debug output).

-V, --version

print the version string and then exit.

## NOTES
According to T10, support for 'background control operations' is indicated by the BOCS bit being set in the Block device characteristics VPD page [0xb1]. The setting of the BOCS bit can be checked with the sg_vpd and sdparm utilities (and it is read only). There is a Background operations control mode page [0xa, 0x6] with a BO_MODE field for modifying the action of this operation. The BO_MODE field can be accessed and possibly modified with the sdparm utility. The BO_STATUS field can be found in the Background operation log page [0x15, 0x2] and that can be viewed with the sg_logs utility.

The current draft describing this area is SBC-4 revision 10 (sbc4r10.pdf) in clause 4.33 . That contains the following example of a background operation: "Advanced background operation may include NAND block erase operations, media read operations, and media write operations (e.g., garbage collection), which may impact response time for normal read requests or write requests from the application client."

## EXIT STATUS
The exit status of sg_bg_ctl is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2016 Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_vpd,sg_logs(sg3_utils); sdparm(sdparm)


title: sg_compare_and_write(8)

summary: send the SCSI COMPARE AND WRITE command

text:
# sg_compare_and_write(8)

## NAME
sg_compare_and_write - send the SCSI COMPARE AND WRITE command

## SYNOPSIS
sg_compare_and_write [--dpo] [--fua] [--fua_nv] [--grpnum=GN] [--help] --in=IF [--inw=WF] --lba=LBA [--num=NUM] [--quiet] [--timeout=TO] [--verbose] [--version] [--wrprotect=WP] [--xferlen=LEN] DEVICE

## DESCRIPTION
Send the SCSI COMPARE AND WRITE command to DEVICE. This utility fetches a compare buffer and a write buffer from either one or two files. If the --inw=WF option is given then the compare buffer is fetched from the file indicated by the --in=IF while the write buffer is fetched from the file indicated by the --inw=WF. If the --inw=WF option is not given then the concatenated compare and write buffers are fetched from the file indicated by the --in=IF option.

Those buffers are expected to each contain NUM blocks of data. The compare starts at logical block address LBA on the DEVICE and if the comparison fails (i.e. the provided compare buffer does not equal the data at LBA on the DEVICE) then the COMPARE AND WRITE command finishes with a sense key of MISCOMPARE. In this case this utility will complete and set an exit status of 14 (which happens to be the sense key value of MISCOMPARE).

If the comparison succeeds then the provided write buffer is stored starting at LBA for NUM blocks on the DEVICE.

The actual number of bytes transferred in the data-out buffer of the COMPARE AND WRITE command may need to be given by the user with the --xferlen=LEN option. LEN defaults to (2 * NUM * 512) which is 1024 for the default NUM of 1. If the block size is other than 512 then the user will need to use --xferlen=LEN option. If protection information is given (indicated by a value of WP other than 0 (the default)) then for a NUM of 1 LEN should be 1040 . Note that the SCSI READ CAPACITY command is not performed by this utility (e.g. to find the block size).

The T10 definition of the SCSI COMPARE AND WRITE command requires that the DEVICE implement the compare and optional write as an uninterrupted series of actions. Depending on some other DEVICE settings a verify operation may occur prior to the compare.

When a mismatch occurs between the compare buffer and the blocks starting at LBA read from the DEVICE the sense buffer containing the MISCOMPARE sense key causes several messages to be sent to stderr (including the offset of the first byte mismatch). To suppress these messages use the --quiet option. With or without the --quiet option the exit status will be set to 14.

This command is defined in SBC-3 whose most recent revision is 36. SBC-3 and other SCSI documents can be found at https://www.t10.org .

## OPTIONS
Arguments to long options are mandatory for short options as well. The options are arranged in alphabetical order based on the long option name.

-d, --dpo

Set the DPO bit in the COMPARE AND WRITE CDB

-f, --fua

Set the FUA bit in the COMPARE AND WRITE CDB

-F, --fua_nv

Set the FUA_NV bit in the COMPARE AND WRITE CDB. This bit was removed in SBC-3 revision 35d and its position marked as "reserved".

-g, --grpnum=GN

where GN is the value to be placed in the group number field in the COMPARE AND WRITE CDB.

-h, --help

output the usage message then exit.

-i, --in=IF

read data (binary) from file named IF. This will either be the combined compare and write buffers (when the --inw=WF option is not given) or just the compare buffer (when the --inw=WF option is given). If IF is '-' then stdin (e.g. a pipe) is read.

-C, --inc=IF

The same as the --in option.

-D, --inw=WF

read data (binary) from file named WF. This will the write buffer that will become the second half of the data-out buffer sent to the DEVICE associated with the COMPARE AND WRITE command. Note that when this option is given then the --in=IF is expected to hold the associated compare buffer.

-l, --lba=LBA

where LBA is the logical block address to start the COMPARE AND WRITE command. Assumed to be in decimal unless prefixed with '0x' or has a trailing 'h'.

-n, --num=NUM

where NUM is the number of blocks, starting at LBA, to read and compare with the verify instance. And given a match, the NUM of blocks to write starting LBA. The default value for NUM is 1.

-q, --quiet

suppress the sense buffer messages associated with a MISCOMPARE sense key that would otherwise be sent to stderr. Still set the exit status to 14 which is the sense key value indicating a MISCOMPARE.

-t, --timeout=TO

where TO is the command timeout value in seconds. The default value is 60 seconds. If NUM is large (or zero) a WRITE SAME command may require considerably more time than 60 seconds to complete.

-v, --verbose

increase the degree of verbosity (debug messages).

-V, --version

output version string then exit.

-w, --wrprotect=WP

set the WRPROTECT field in the cdb to WP. The default value is 0 which implies no protection information is sent (along with the user data) by this utility.

-x, --xferlen=LEN

where LEN is the data out buffer length in byte. It defaults to (2 * NUM * 512) bytes. If the DEVICE block size is other than 512 bytes or WP is non-zero (implying additional protection information) then this default will be incorrect; the use must supply the correct value for LEN

## NOTES
Various numeric arguments (e.g. LBA) may include multiplicative suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

## EXAMPLES
Before overwriting the first two blocks of whatever (SCSI) storage device that is chosen, take a small backup. The logical block size is assumed to be 512 bytes. Take a copy (in backup01.bin) of the first two blocks::

\# sg_dd if=/dev/sg1 bs=512 of=backup01.bin count=2

2+0 records in

2+0 records out

WARNING: if /dev/sg1 corresponds to a disk on your system that contains currently mounted file systems, do _not_ continue. If you can, unmount all file systems on that disk. If that is not possible, use another disk with no mounted file systems on it. In Linux the scsi_debug driver is a good candidate for experimentation.

Now fill the first block with 0xff bytes:

\# sg_dd iflag=ff bs=512 of=/dev/sg1 count=1

1+0 records in

1+0 records out

and the second block with 0x0 bytes:

\# sg_dd iflag=00 bs=512 seek=1 of=/dev/sg1 count=1

1+0 records in

1+0 records out

Now copy those two blocks into a file:

\# sg_dd if=/dev/sg1 bs=512 of=ff00.bin count=2

2+0 records in

2+0 records out

Now we can do a compare and write command. It is told to compare the first block (i.e. LBA 0) with the first block in the given file (i.e. ff00.bin). If they are equal (they should be both full of 0xff bytes). Since the compare succeeds, it will write the second block in ff00.bin over LBA 0:

\# sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1

No news is good news. Now if we do that command again:

\# sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1

Miscompare at byte offset: 0 [0x0]

sg_compare_and_write failed: Miscompare

This is expected. The first sg_compare_and_write ended up writing 0x0 bytes over LBA 0x0. The second sg_compare_and_write command compares LBA 0x0 with 0xff bytes and fails immediately (i.e. at byte offset: 0). Now we will overwrite the first 3 bytes of ff00.bin with 0x0:

\# sg_dd bs=1 iflag=00 of=ff00.bin count=3

3+0 records in

3+0 records out

Notice the 'bs=1' operand. The dd utility (and thus sg_dd) is very useful for doing small binary edits on a file. Now if we do that sg_compare_and_write again, it still fails but with a small difference:

\# sg_compare_and_write --in=ff00.bin --lba=0 --num=1 /dev/sg1

Miscompare at byte offset: 3 [0x3]

sg_compare_and_write failed: Miscompare

So the bytes at offset 0, 1, and 2 compared equal but not the byte at offset 3. The SCSI COMPARE AND WRITE will stop on the first micompared byte.

## EXIT STATUS
The exit status of sg_compare_and_write is 0 when it is successful. If the compare step fails then the exit status is 14. For other exit status values see the EXIT STATUS section in the sg3_utils(8) man page.

Earlier versions of this utility set an exit status of 98 when there was a MISCOMPARE.

## AUTHORS
Written by Shahar Salzman. Maintained by Douglas Gilbert. Additions by Eric Seppanen.

## REPORTING BUGS
Report bugs to shahar.salzman@kaminario.com or dgilbert@interlog.com

## COPYRIGHT
Copyright © 2012-2020 Kaminario Technologies LTD

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the <organization> nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL Kaminario Technologies LTD BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

## SEE ALSO
sg_xcopy, sg_receive_copy_results(sg3_utils)


title: sg_copy_results(8)

text:
# sg_copy_results(8)

## NAME
sg_copy_results - send SCSI RECEIVE COPY RESULTS command (XCOPY related)

## SYNOPSIS
sg_copy_results [--failed|--params|--receive|--status] [--help] [--hex] [--list_id=ID] [--readonly] [--verbose] [--version] [--xfer_len=BTL] DEVICE

## DESCRIPTION
This utility is designed to query the status of the SCSI Extended Copy (XCOPY) facility (see SPC-3 revision 23 sections 6.3 and 6.17), present in some modern storage arrays. This utility sends a SCSI RECEIVE COPY RESULTS command to the given DEVICE and displays the response.

During the draft stages of SPC-4 the T10 committee has expanded the XCOPY command so that it now has two variants: "LID1" (for a List Identifier length of 1 byte) and "LID4" (for a List Identifier length of 4 bytes). This utility supports the older, LID1 variant which is also found in SPC-3 and earlier. While the LID1 variant in SPC-4 is command level (binary) compatible with XCOPY as defined in SPC-3, some of the command naming has changed. This utility uses the older, SPC-3 XCOPY names.

The command has four distinct modes of operation, distinguished by the service action field:

COPY STATUS [SPC-4: RECEIVE COPY STATUS(LID1)]

Displays the current status of the EXTENDED COPY command identified by the list id field.

RECEIVE DATA [SPC-4: RECEIVE COPY DATA(LID1)]

Return the held data read by the EXTENDED COPY command identified by the list id field. This option is only meaningful if the respective segment descriptor are supported.

OPERATING PARAMETERS [SPC-4: RECEIVE COPY OPERATING PARAMETERS]

Return copy manager operating parameters. This option is also useful to determine if the SCSI Extended Copy facility is supported.

FAILED SEGMENT DETAILS [SPC-4: RECEIVE COPY FAILURE DETAILS(LID1)]

Return copy target device sense data and other information about any failed segments.

## OPTIONS
Arguments to long options are mandatory for short options as well.

-f, --failed

sets the service action field to FAILED SEGMENT DETAILS [4].

-h, --help

output the usage message then exit.

-H, --hex

prints out the response buffer in hex.

-l, --list_id=ID

sets the list identifier field to ID (default: 0).

-p, --params

sets the service action field to OPERATING PARAMETERS [3]. This is the default.

-R, --readonly

open the DEVICE read-only (e.g. in Unix with the O_RDONLY flag). The default is to open it read-write.

-r, --receive

sets the service action field to RECEIVE DATA [1].

-s, --status

sets the service action field to COPY STATUS [0].

-v, --verbose

increase the level of verbosity, (i.e. debug output).

-V, --version

print the version string and then exit.

-x, --xfer_len=BTL

sets the allocation length field to BTL. It is the byte transfer length and is the maximum (byte) size of the response. BTL must be less than 10000 and defaults to 520.

## NOTES
Decoding of RECEIVE DATA service action is not implemented.

In a similar way the functionality of sg_xcopy has been ported to the more general ddpt utility (and package), the functionality of this utility has been ported to the ddptctl utility.

## EXAMPLES
Query the operating parameters for a device:

\# sg_copy_results -p /dev/sdo

Receive copy results (report operating parameters):

Supports no list identifier: no

Maximum target descriptor count: 2

Maximum segment descriptor count: 1

Maximum descriptor list length: 92 bytes

Maximum segment length: 33553920 bytes

Inline data not supported

Held data limit: 0 bytes

Maximum stream device transfer size: 0 bytes

Total concurrent copies: 0

Maximum concurrent copies: 255

Data segment granularity: 512 bytes

Inline data granularity: 1 bytes

Held data granularity: 1 bytes

Implemented descriptor list:

Segment descriptor 0x02: Copy from block device to block device

Target descriptor 0xe4: Identification descriptor

## EXIT STATUS
The exit status of sg_copy_results is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

## AUTHORS
Written by Douglas Gilbert.

## REPORTING BUGS
Report bugs to <dgilbert at interlog dot com>.

## COPYRIGHT
Copyright © 2012-2014 Hannes Reinecke and Douglas Gilbert

This software is distributed under a BSD-2-Clause license. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

## SEE ALSO
sg_xcopy(sg3_utils), ddpt,ddptctl(ddpt)