title: sg_dd(8)

text:
# sg_dd(8)

## NAME
sg_dd - copy data to and from files and devices, especially SCSI devices

## SYNOPSIS
sg_dd [bs=BS] [conv=CONV] [count=COUNT] [ibs=BS] [if=IFILE] [iflag=FLAGS] [obs=BS] [of=OFILE] [oflag=FLAGS] [seek=SEEK] [skip=SKIP] [--help] [--verbose] [--version]

[blk_sgio={0|1}] [bpt=BPT] [cdbsz={6|10|12|16}] [cdl=CDL] [coe={0|1|2|3}] [coe_limit=CL] [dio={0|1}] [odir={0|1}] [of2=OFILE2] [retries=RETR] [sync={0|1}] [time={0|1}[,TO]] [verbose=VERB] [--dry-run] [--progress] [--verify]

## DESCRIPTION
Copy data to and from any files. Specialized for "files" that are Linux SCSI generic (sg) devices, raw devices or other devices that support the SG_IO ioctl (which are only found in the lk 2.6 series). Similar syntax and semantics to dd(1) command.

The first group in the synopsis above are "standard" Unix dd(1) operands. The second group are extra options added by this utility. Both groups are defined below.

When the --verify option is given, then the read side is the same but the on the write side, the WRITE SCSI command is replaced by the VERIFY SCSI command. If any VERIFY commands yields a sense key of MISCOMPARE then the verify operation will stop. The --verify option can only be used when OFILE is either a sg device or a block device with oflag=sgio also given. When the --verify option is used, this utility works in a similar fashion to the Unix cmp(1) command.

This utility is only supported on Linux whereas most other utilities in the sg3_utils package have been ported to other operating systems. A utility called "ddpt" has similar syntax and functionality to sg_dd. ddpt drops some Linux specific features while adding some other generic features. This allows ddpt to be ported to other operating systems.

For support of NVMe storage devices see the section below titled: NVME SUPPORT .

## OPTIONS
blk_sgio={0|1}

when set to 0, block devices (e.g. /dev/sda) are treated like normal files (i.e. read(2) and write(2) are used for IO). When set to 1, block devices are assumed to accept the SG_IO ioctl and SCSI commands are issued for IO. This is only supported for 2.6 series kernels. Note that ATAPI devices (e.g. cd/dvd players) use the SCSI command set but ATA disks do not (unless there is a protocol conversion as often occurs in the USB mass storage class). If the input or output device is a block device partition (e.g. /dev/sda3) then setting this option causes the partition information to be ignored (since access is directly to the underlying device). Default is 0. See the 'sgio' flag.

bpt=BPT

each IO transaction will be made using BPT blocks (or less if near the end of the copy). Default is 128 for logical block sizes less that 2048 bytes, otherwise the default is 32. So for bs=512 the reads and writes will each convey 64 KiB of data by default (less if near the end of the transfer or memory restrictions). When cd/dvd drives are accessed, the logical block size is typically 2048 bytes and bpt defaults to 32 which again implies 64 KiB transfers. The block layer when the blk_sgio=1 option is used has relatively low upper limits for transfer sizes (compared to sg device nodes, see /sys/block/<dev_name>/queue/max_sectors_kb ).

bs=BS

where BS must be the logical block size of the physical device (if either the input or output files are accessed via SCSI commands). Note that this differs from dd(1) which permits BS to be an integral multiple. Default is 512 which is usually correct for disks but incorrect for cdroms (which normally have 2048 byte blocks). For this utility the maximum size of each individual IO operation is BS * BPT bytes.

cdbsz={6|10|12|16}

size of SCSI READ and/or WRITE commands issued on sg device names (or block devices when 'iflag=sgio' and/or 'oflag=sgio' is given). Default is 10 byte SCSI command blocks (unless calculations indicate that a 4 byte block number may be exceeded or BPT is greater than 16 bits (65535), in which case it defaults to 16 byte SCSI commands).

cdl=CDL

allows setting of command duration limits. CDL is either a single value or two values separated by a comma. If one value is given, it applies to both IFILE and OFILE (if they are pass-through devices). If two values are given, the first applies to IFILE while the second applies to OFILE. The value may be from 0 to 7 where 0 is the default and means there are no command duration limits. Command duration limits are only supported by 16 byte READ and WRITE commands (plus READ(32), WRITE(32) and the WRITE SCATTERED command, bit they are used by this utility). If the cdbsz operand is not given and would have a value less than 16, then if CDL is greater than 0, the cdbsz is increased to 16.

Command duration limits can be accesses and changed in the Command duration limit A and B mode pages, plus the Command duration limit T2A and T2B mode pages. The sdparm utility may be used to access and change these mode pages.

coe={0|1|2|3}

set to 1 or more for continue on error ('coe'). Only applies to errors on sg devices or block devices with the 'sgio' flag set. Thus errors on other files will stop sg_dd. Default is 0 which implies stop on any error. See the 'coe' flag for more information.

coe_limit=CL

where CL is the maximum number of consecutive bad blocks stepped over (due to "coe>0") on reads before the copy terminates. This only applies when IFILE is accessed via the SG_IO ioctl. The default is 0 which is interpreted as no limit. This option is meant to stop the copy soon after unrecorded media is detected while still offering "continue on error" capability.

conv=sparse

see the CONVERSIONS section below.

count=COUNT

copy COUNT blocks from IFILE to OFILE. Default is the minimum (of IFILE and OFILE) number of blocks that sg devices report from SCSI READ CAPACITY commands or that block devices (or their partitions) report. Normal files are not probed for their size. If skip=SKIP or seek=SEEK are given and the count is derived (i.e. not explicitly given) then the derived count is scaled back so that the copy will not overrun the device. If the file name is a block device partition and COUNT is not given then the size of the partition rather than the size of the whole device is used. If COUNT is not given (or count=-1) and cannot be derived then an error message is issued and no copy takes place.

dio={0|1}

default is 0 which selects indirect (buffered) IO on sg devices. Value of 1 attempts direct IO which, if not available, falls back to indirect IO and notes this at completion. If direct IO is selected and /sys/module/sg/parameters/allow_dio has the value of 0 then a warning is issued (and indirect IO is performed). For finer grain control use 'iflag=dio' or 'oflag=dio'.

ibs=BS

if given must be the same as BS given to 'bs=' option.

if=IFILE

read from IFILE instead of stdin. If IFILE is '-' then stdin is read. Starts reading at the beginning of IFILE unless SKIP is given.

iflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with IFILE and are ignored when IFILE is stdin.

obs=BS

if given must be the same as BS given to 'bs=' option.

odir={0|1}

when set to one opens block devices (e.g. /dev/sda) with the O_DIRECT flag. User memory buffers are aligned to the page size when set. The default is 0 (i.e. the O_DIRECT flag is not used). Has no effect on sg, normal or raw files. If blk_sgio is also set then both are honoured: block devices are opened with the O_DIRECT flag and SCSI commands are issued via the SG_IO ioctl.

of=OFILE

write to OFILE instead of stdout. If OFILE is '-' then writes to stdout. If OFILE is /dev/null then no actual writes are performed. If OFILE is '.' (period) then it is treated the same way as /dev/null (this is a shorthand notation). If OFILE exists then it is _not_ truncated; it is overwritten from the start of OFILE unless 'oflag=append' or SEEK is given.

of2=OFILE2

write output to OFILE2. The default action is not to do this additional write (i.e. when this option is not given). OFILE2 is assumed to be a normal file or a fifo (i.e. a named pipe). OFILE2 is opened for writing, created if necessary, and closed at the end of the transfer. If OFILE2 is a fifo (named pipe) then some other command should be consuming that data (e.g. 'md5sum OFILE2'), otherwise this utility will block.

oflag=FLAGS

where FLAGS is a comma separated list of one or more flags outlined below. These flags are associated with OFILE and are ignored when OFILE is /dev/null, '.' (period), or stdout.

retries=RETR

sometimes retries at the host are useful, for example when there is a transport error. When RETR is greater than zero then SCSI READs and WRITEs are retried on error, RETR times. Default value is zero.

seek=SEEK

start writing SEEK bs-sized blocks from the start of OFILE. Default is block 0 (i.e. start of file).

skip=SKIP

start reading SKIP bs-sized blocks from the start of IFILE. Default is block 0 (i.e. start of file).

sync={0|1}

when 1, does SYNCHRONIZE CACHE command on OFILE at the end of the transfer. Only active when OFILE is a sg device file name or a block device and 'blk_sgio=1' is given.

time={0|1}[,TO]

when 1, times transfer and does throughput calculation, outputting the results (to stderr) at completion. When 0 (default) doesn't perform timing.

If that value is followed by a comma, then TO is the command timeout in seconds for SCSI READ, WRITE or VERIFY commands issued by this utility. The default is 60 seconds.

verbose=VERB

as VERB increases so does the amount of debug output sent to stderr. Default value is zero which yields the minimum amount of debug output. A value of 1 reports extra information that is not repetitive. A value 2 reports cdbs and responses for SCSI commands that are not repetitive (i.e. other that READ and WRITE). Error processing is not considered repetitive. Values of 3 and 4 yield output for all SCSI commands (and Unix read() and write() calls) so there can be a lot of output. This only occurs for scsi generic (sg) devices and block devices when the 'blk_sgio=1' option is set.

-d, --dry-run

does all the command line parsing and preparation but bypasses the actual copy or read. That preparation may include opening IFILE or OFILE to determine their lengths. This option may be useful for testing the syntax of complex command line invocations in advance of executing them.

-h, --help

outputs usage message and exits.

-p, --progress

this option causes a progress report to be output every two minutes until the copy is complete. After the copy is complete a line with "completed" is printed to distinguish the final report from the prior progress reports. When used twice the progress report is every minute, when used three times the progress report is every 30 seconds.

If this option is given then the 'time=1' option is set implicitly.

-v, --verbose

when used once, this is equivalent to verbose=1. When used twice (e.g. "-vv") this is equivalent to verbose=2, etc.

-x, --verify

do a verify operation (like Unix command cmp(1)) rather than a copy. Cannot be used with "oflag=sparse". of=OFILE must be given and OFILE must be an sg device or a block device with "oflag=sgio" also given. Uses the SCSI VERIFY command with the BYTCHK field set to 1. The VERIFY command is used instead of WRITE when this option is given. There is no VERIFY(6) command. Stops on the first miscompare unless oflag=coe is given.

-V, --version

outputs version number information and exits.

## CONVERSIONS
One or more conversions can be given to the "conv=" option. If more than one is given, they should be comma separated. sg_dd does not perform the traditional dd conversions (e.g. ASCII to EBCDIC). Recently added conversions overlap somewhat with the flags so some conversions are now supported by sg_dd.

nocreat

this conversion has the same effect as "oflag=nocreat", namely: OFILE must exist, it will not be created.

noerror

this conversion is very close to "iflag=coe" and is treated as such. See the "coe" flag. Note that an error on OFILE will stop the copy.

notrunc

this conversion is accepted for compatibility with dd and ignored since the default action of this utility is not to truncate OFILE.

null

has no affect, just a placeholder.

sparse

FreeBSD supports "conv=sparse" so the same syntax is supported in sg_dd. See "sparse" in the FLAGS sections for more information.

sync

is ignored by sg_dd. With dd it means supply zero fill (rather than skip) and is typically used like this "conv=noerror,sync" to have the same functionality as sg_dd's "iflag=coe".

## FLAGS
Here is a list of flags and their meanings:

00

this flag is only active with iflag= and when given replaces if=IFILE. If both are given an error is generated. The input will be a stream of zeros, similar to using "if=/dev/zero" alone (but a little quicker), apart from the following case.

If 'iflag=00,ff' is given then the block address (lower 32 bits, in 4 bytes, big endian) is placed, multiple times, in each block. The block address takes into account the skip=SKIP setting. The sgp_dd utility has a --chkaddr option that complements this option.

append

causes the O_APPEND flag to be added to the open of OFILE. For regular files this will lead to data appended to the end of any existing data. Cannot be used together with the seek=SEEK option as they conflict. The default action of this utility is to overwrite any existing data from the beginning of the file or, if SEEK is given, starting at block SEEK. Note that attempting to 'append' to a device file (e.g. a disk) will usually be ignored or may cause an error to be reported.

coe

continue on error. Only active for sg devices and block devices that have the 'sgio' flag set. 'iflag=coe oflag=coe' and 'coe=1' are equivalent. Use this flag twice (e.g. 'iflag=coe,coe') to have the same action as the 'coe=2'. A medium, hardware or blank check error while reading will re-read blocks prior to the bad block, then try to recover the bad block, supplying zeros if that fails, and finally re-read the blocks after the bad block. A medium, hardware or blank check error while writing is noted and ignored. A miscompare sense key during a VERIFY command (i.e. --verify given) is noted and ignored when 'oflag=coe'. The recovery of the bad block when reading uses the SCSI READ LONG command if 'coe' given twice or more (also with the command line option 'coe=2'). Further, the READ LONG will set its CORRCT bit if 'coe' given thrice. SCSI disks may automatically try and remap faulty sectors (see the AWRE and ARRE in the read write error recovery mode page (the sdparm utility can access and possibly change these attributes)). Errors occurring on other files types will stop sg_dd. Error messages are sent to stderr. This flag is similar to 'conv=noerror,sync' in the dd(1) utility. See note about READ LONG below.

dio

request the sg device node associated with this flag does direct IO. If direct IO is not available, falls back to indirect IO and notes this at completion. If direct IO is selected and /sys/module/sg/parameters/allow_dio has the value of 0 then a warning is issued (and indirect IO is performed).

direct

causes the O_DIRECT flag to be added to the open of IFILE and/or OFILE. This flag requires some memory alignment on IO. Hence user memory buffers are aligned to the page size. Has no effect on sg, normal or raw files. If 'iflag=sgio' and/or 'oflag=sgio' is also set then both are honoured: block devices are opened with the O_DIRECT flag and SCSI commands are issued via the SG_IO ioctl.

dpo

set the DPO bit (disable page out) in SCSI READ and WRITE commands. Not supported for 6 byte cdb variants of READ and WRITE. Indicates that data is unlikely to be required to stay in device (e.g. disk) cache. May speed media copy and/or cause a media copy to have less impact on other device users.

dsync

causes the O_SYNC flag to be added to the open of IFILE and/or OFILE. The 'd' is prepended to lower confusion with the 'sync=0|1' option which has another action (i.e. a synchronisation to media at the end of the transfer).

excl

causes the O_EXCL flag to be added to the open of IFILE and/or OFILE.

ff

this flag is only active with iflag= and when given replaces if=IFILE. If both are given an error is generated. The input will be a stream of 0xff bytes (or all bits set), apart from the following case.

If 'iflag=00,ff' is given then the block address (lower 32 bits, in 4 bytes, big endian) is placed, multiple times, in each block. The block address takes into account the skip=SKIP setting.

flock

after opening the associated file (i.e. IFILE and/or OFILE) an attempt is made to get an advisory exclusive lock with the flock() system call. The flock arguments are "FLOCK_EX | FLOCK_NB" which will cause the lock to be taken if available else a "temporarily unavailable" error is generated. An exit status of 90 is produced in the latter case and no copy is done.

fua

causes the FUA (force unit access) bit to be set in SCSI READ and/or WRITE commands. This only has an effect with sg devices or block devices that have the 'sgio' flag set. The 6 byte variants of the SCSI READ and WRITE commands do not support the FUA bit.

nocache

use posix_fadvise() to advise corresponding file there is no need to fill the file buffer with recently read or written blocks.

nocreat

this flag is only active in oflag=FLAGS. If present then OFILE will be opened if it exists. If OFILE doesn't exist then an error is generated. Without this flag a regular (empty) file named OFILE will be created (and then filled). For production quality scripts where OFILE is a device node (e.g. '/dev/sdc') this flag is recommended. It guards against the remote possibility of 'dev/sdc' disappearing temporarily (e.g. a USB memory key removed) resulting in a large regular file called '/dev/sdc' being created.

null

has no affect, just a placeholder.

pt

has the same meaning as the sgio flag. Added for compatibility with the ddpt utility.

random

this flag is only active with iflag= and when given replaces if=IFILE. If both are given an error is generated. The input will be a stream of pseudo random bytes. The Linux getrandom(2) system call is used to create a seed and there after mrand48(3) is used to generate a pseudo random sequence, 4 bytes at a time. The quality of the randomness can be viewed with the ent(1) utility. This is not a high quality random number generator, it is built for speed, not quality. One application is checking the correctness of the copy and verify operations of this utility.

sgio

causes block devices to be accessed via the SG_IO ioctl rather than standard UNIX read() and write() commands. When the SG_IO ioctl is used the SCSI READ and WRITE commands are used directly to move data. sg devices always use the SG_IO ioctl. This flag offers finer grain control compared to the otherwise identical 'blk_sgio=1' option.

sparse

after each BS * BPT byte segment is read from the input, it is checked for being all zeros. If so, nothing is written to the output file unless this is the last segment of the transfer. This flag is only active with the oflag option. It cannot be used when the output is not seekable (e.g. stdout). It is ignored if the output file is /dev/null . Note that this utility does not remove the OFILE prior to starting to write to it. Hence it may be advantageous to manually remove the OFILE if it is large prior to using oflag=sparse. The last segment is always written so regular files will show the same length and so programs like md5sum and sha1sum will generate the same value regardless of whether oflag=sparse is given or not. This option may be used when the OFILE is a raw device but is probably only useful if the device is known to contain zeros (e.g. a SCSI disk after a FORMAT command).

## RETIRED OPTIONS
Here are some retired options that are still present:

append=0 | 1

when set, equivalent to 'oflag=append'. When clear the action is to overwrite the existing file (if it exists); this is the default. See the 'append' flag.

fua=0 | 1 | 2 | 3

force unit access bit. When 3, fua is set on both IFILE and OFILE; when 2, fua is set on IFILE;, when 1, fua is set on OFILE; when 0 (default), fua is cleared on both. See the 'fua' flag.

## NOTES
Block devices (e.g. /dev/sda and /dev/hda) can be given for IFILE. If neither '-iflag=direct', 'iflag=sgio' nor 'blk_sgio=1' is given then normal block IO involving buffering and caching is performed. If only '-iflag=direct' is given then the buffering and caching is bypassed (this is applicable to both SCSI devices and ATA disks). If 'iflag=sgio' or 'blk_sgio=1' is given then the SG_IO ioctl is used on the given file causing SCSI commands to be sent to the device and that also bypasses most of the actions performed by the block layer (this is only applicable to SCSI devices, not ATA disks). The same applies for block devices given for OFILE.

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

The COUNT, SKIP and SEEK arguments can take 64 bit values (i.e. very big numbers). Other values are limited to what can fit in a signed 32 bit number.

Data usually gets to the user space in a 2 stage process: first the SCSI adapter DMAs into kernel buffers and then the sg driver copies this data into user memory (write operations reverse this sequence). This is called "indirect IO" and there is a 'dio' option to select "direct IO" which will DMA directly into user memory. Due to some issues "direct IO" is disabled in the sg driver and needs a configuration change to activate it. This is typically done with 'echo 1 > /sys/module/sg/parameters/allow_dio'.

All informative, warning and error output is sent to stderr so that dd's output file can be stdout and remain unpolluted. If no options are given, then the usage message is output and nothing else happens.

Even if READ LONG succeeds on a "bad" block when 'coe=2' (or 'coe=3') is given, the recovered data may not be useful. There are no guarantees that the user data will appear "as is" in the first 512 bytes.

A raw device must be bound to a block device prior to using sg_dd. See raw(8) for more information about binding raw devices. To be safe, the sg device mapping to SCSI block devices should be checked with sg_map before use.

Disk partition information can often be found with fdisk(8) [the "-ul" argument is useful in this respect].

For sg devices (and block devices when blk_sgio=1 is given) this utility issues SCSI READ and WRITE (SBC) commands which are appropriate for disks and reading from CD/DVD/HD-DVD/BD drives. Those commands are not formatted correctly for tape devices so sg_dd should not be used on tape devices. If the largest block address of the requested transfer exceeds a 32 bit block number (i.e 0xffff) then a warning is issued and the sg device is accessed via SCSI READ(16) and WRITE(16) commands.

The attributes of a block device (partition) are ignored when 'blk_sgio=1' is used. Hence the whole device is read (rather than just the second partition) by this invocation:

sg_dd if=/dev/sdb2 blk_sgio=1 of=t bs=512

## NVME SUPPORT
Some support for copying from and to NVMe devices in Linux have been added. There are two varieties of NVME "char" devices, examples: /dev/nvme<cid> and /dev/ng<cid>n<nsid> where <cid> is the controller identifier (starting at 0) and <nsid> is the NVMe namespace identifier (starting at 1). The latter form is called "nvme-generic" in /proc/devices . The NVMe block devices have the form: /dev/nvme<cid>n<nsid>[p<part_id>] where the optional <part_id> is the partition identifier (starting at 1). In the case of NVMe block devices the default action of sg_dd is to access them using standard Unix IO (i.e. read(2) or write(2)). To access them using SCSI/NVMe commands, the flag "sgio" or "pt" needs to be given (e.g. iflag=pt if=/dev/nvme0n1 ).

Just as with partitions on SCSI disks, it is dangerous to access NVMe partitions (e.g. iflag=pt if=/dev/nvme0n1p2) using a pass-through interface. The reason is that both SCSI and NVMe commands are oblivious to any partitioning arrangement which Linux (or any other OS) has set up on those disks. In other words, in the above example the "p2" at the end of if=/dev/nvme0n1p2 is ignored when a pass-through is being used.

The READ and WRITE commands in NVMe are in the "NVM" command set which requires a NVMe namespace to be specified. This means that the char device /dev/nvme0 is not useful for the utility, only administrative commands can be sent to it. That leaves the /dev/ng<cid>n<nsid> as the only NVMe "char" device that can be used with this utility. Since it is not a block device, the standard Unix read(2) and write(2) will not work with it; so the pass-through interface, issuing SCSI/NVME commands, is assumed by this utility.

The term "SCSI/NVME command" refers to the fact that this utility issues SCSI commands and a lower level, within libsgutils, converts them to the corresponding NVMe commands. This action is known as a SCSI to NVMe Translation Layer (SNTL) and the NVMe consortium wrote a white paper on it early in the development of NVMe.

## EXAMPLES
Looks quite similar in usage to dd:

sg_dd if=/dev/sg0 of=t bs=512 count=1MB

This will copy 1 million 512 byte blocks from the device associated with /dev/sg0 (which should have 512 byte blocks) to a file called t. Assuming /dev/sda and /dev/sg0 are the same device then the above is equivalent to:

dd if=/dev/sda iflag=direct of=t bs=512 count=1000000

although dd's speed may improve if bs was larger and count was suitably reduced. The use of the 'iflag=direct' option bypasses the buffering and caching that is usually done on a block device.

Using a raw device to do something similar on a ATA disk:

raw /dev/raw/raw1 /dev/hda

sg_dd if=/dev/raw/raw1 of=t bs=512 count=1MB

To copy a SCSI disk partition to an ATA disk partition:

raw /dev/raw/raw2 /dev/hda3

sg_dd if=/dev/sg0 skip=10123456 of=/dev/raw/raw2 bs=512

This assumes a valid partition is found on the SCSI disk at the given skip block address (past the 5 GB point of that disk) and that the partition goes to the end of the SCSI disk. An explicit count is probably a safer option. The partition is copied to /dev/hda3 which is an offset into the ATA disk /dev/hda . The exact number of blocks read from /dev/sg0 are written to /dev/hda (i.e. no padding).

To time a streaming read of the first 1 GB (2 ** 30 bytes) on a disk this utility could be used:

sg_dd if=/dev/sg0 of=/dev/null bs=512 count=2m time=1

On completion this will output a line like: "time to transfer data was 18.779506 secs, 57.18 MB/sec". The "MB/sec" in this case is 1,000,000 bytes per second.

The 'of2=' option can be used to copy data and take a md5sum of it without needing to re-read the data:

mkfifo fif

md5sum fif &

sg_dd if=/dev/sg3 iflag=coe of=sg3.img oflag=sparse of2=fif bs=512

This will image /dev/sg3 (e.g. an unmounted disk) and place the contents in the (sparse) file sg3.img . Without re-reading the data it will also perform a md5sum calculation on the image.

## SIGNALS
The signal handling has been borrowed from dd: SIGINT, SIGQUIT and SIGPIPE output the number of remaining blocks to be transferred and the records in + out counts; then they have their default action. SIGUSR1 causes the same information to be output yet the copy continues. All output caused by signals is sent to stderr.

## EXIT STATUS
The exit status of sg_dd is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Since this utility works at a higher level than individual commands, and there are 'coe' and 'retries' flags, individual SCSI command failures do not necessary cause the process to exit.

An additional exit status of 90 is generated if the flock flag is given and some other process holds the advisory exclusive lock.

## AUTHORS
Written by Douglas Gilbert and Peter Allworth.

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

## COPYRIGHT
Copyright © 2000-2023 Douglas Gilbert

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

## SEE ALSO
cmp(1)

There is a web page discussing sg_dd at https://sg.danny.cz/sg/sg_dd.html

A POSIX threads version of this utility called sgp_dd is in the sg3_utils package. Another version from that package is called sgm_dd and it uses memory mapped IO to speed transfers from sg devices.

The lmbench package contains lmdd which is also interesting. For moving data to and from tapes see dt which is found at https://www.scsifaq.org/RMiller_Tools/index.html

To change mode parameters that effect a SCSI device's caching and error recovery see sdparm(sdparm)

To verify the data on the media or to verify it against some other copy of the data see sg_verify(sg3_utils)

See also raw(8), dd(1), ddrescue(GNU), ddpt


title: sg_decode_sense(8)

summary: decode SCSI sense and related data

text:
# sg_decode_sense(8)

## NAME
sg_decode_sense - decode SCSI sense and related data

## SYNOPSIS
sg_decode_sense [--binary=BFN] [--cdb] [--err=ES] [--file=HFN] [--help] [--hex] [--inhex=HFN] [--ignore-first] [--json[=JO]] [--js-file=JFN] [--nodecode] [--nospace] [--status=SS] [--verbose] [--version] [--write=WFN] [H1 H2 H3 ...]

## DESCRIPTION
This utility takes SCSI sense data in binary or as a sequence of ASCII hexadecimal bytes and decodes it. The primary reference for the decoding is SPC-5 ANSI INCITS 502-2020 and the most recent draft SPC-6 revision 6 which can be found at https://www.t10.org and other locations on the internet.

SCSI sense data is often found in kernel log files as a result of something going wrong or may be an informative warning. It is often shown as a sequence of hexadecimal bytes, starting with 70, 71, 72, 73, f0 or f1. Sense data could be up to 252 bytes long but typically is much shorter than that, 18 bytes long is often seen and is usually associated with the older "fixed" format sense data.

The sense data can be provided on the command line or in a file. If given on the command line the sense data should be a sequence of hexadecimal bytes separated by space. Alternatively a file can be given with the contents in binary or ASCII hexadecimal bytes. The latter form can contain several lines each with none, one or more ASCII hexadecimal bytes separated by space (comma or tab). The hash symbol may appear and it and the rest of the line is ignored making it useful for comments.

If the --cdb option is given then rather than viewing the given hex arguments as sense data, it is viewed as a SCSI command descriptor block (CDB). In this case the command name is printed out. That name is based on the first hex byte given (know as the opcode) and optionally on another field called the "service action".

Another alternate action is when the --err=ES is given. ES is assumed to be an "exit status" value between 0 and 255 from one of the utilities in this package. A descriptive string is printed. Other options are ignored apart from --verbose.

When the --nodecode option is given, this utility may be used to convert a binary file to hexadecimal or vice versa. The data converted does not need to be related to SCSI sense data nor CDBs.

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

-b, --binary=BFN

the data is read in binary from a file called BFN. The option cannot be given with --file=HFN or --inhex=HFN as they contradict. The data is assumed to be sense data unless the fI--nodecode is given.

-c, --cdb

treat the given string of hex arguments as bytes in a SCSI CDB and decode the command name.

-e, --err=ES

ES should be an "exit status" value between 0 and 255 that is available from the shell (i.e. the utility's execution context) after the utility is finished. By default an indicative error message is printed to stdout; and if the --verbose option is given once (or an odd number of times) then the message is instead printed to stderr. If --verbose is given two or more times a longer form of the message is output. In all cases the message is less than 128 characters long with one trailing line feed. All other command line options and arguments are ignored.

-f, --file=HFN

the sense data is read in ASCII hexadecimal from a file called HFN. The sense data should appear as a sequence of bytes separated by space, comma, tab, hyphen or newline. Everything from and including a hash symbol to the end of that line is ignored. If --nospace is set then no separator is required between the ASCII hexadecimal digits in HFN with bytes decoded from pairs of ASCII hexadecimal digits.

-h, --help

output the usage message then exit.

-H, --hex

this option is used once in conjunction with --write=WFN in order to change the output written to WFN to lines of ASCII hex bytes suitable for a C language compiler. Each line contains up to 16 bytes (e.g. a line starting with "0x3b,0x07,0x00,0xff").

In other cases (i.e. when --write=WFN is not given, or this option is given more than once) then the output is as described in the sg3_utils(8) manpage.

The combination of --inhex=HFN and this option used three times can be useful to converting hexadecimal bytes (e.g. hyphen separated) into a more regular form. The short option form is more convenient for invoking this option three times (e.g. '-HHH').

-i, --inhex=HFN

same action as --file=HFN. This option was added for compatibility with other utilities in this package that have a --inhex= option.

-I, --ignore-first

many programs that output hex bytes (e.g. 'hexdump -C') have a running count (or index) in the first column of each line. This option ignores the first hexadecimal value on each line. This option has no effect if --binary=BFN or --nospace are given. Blank lines and any character from and after "#" on a line are ignored. Useful with the --file=HFN and --nodecode options.

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

output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=".

See sg3_utils_json manpage or use '?' for JO to get a summary.

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

-N, --nodecode

Do not decode the given data as sense or a cdb. Useful when arbitrary data is given (e.g. when converting hex to binary or vice versa).

-n, --nospace

expect ASCII hexadecimal to be a string of hexadecimal digits with no spaces between them. Bytes are decoded by taking two hexadecimal digits at a time, so an even number of digits is expected. The string of hexadecimal digits may be on the command line (replacing "H1 H2 H3") or spread across multiple lines the HFN given to --file=. On the command line, spaces (or other whitespace characters) between sequences of hexadecimal digits are ignored; the maximum command line hex string is 1023 characters long.

-s, --status=SS

where SS is a SCSI status byte value, given in hexadecimal. The SCSI status byte is related to, but distinct from, sense data.

-v, --verbose

increase the degree of verbosity (debug messages).

-V, --version

output version string then exit.

-w, --write=WFN

writes the sense data out to a file called WFN. If necessary WFN is created. If WFN exists then it is truncated prior to writing the sense data to it. If the --hex option is also given then ASCII hex is written to WFN (see the --hex option description); otherwise binary is written to WFN. This option is a convenience and may be helpful in converting the ASCII hexadecimal representation of sense data (or anything else) into the equivalent binary or a compilable ASCII hex form.

## NOTES
Unlike most utilities in this package, this utility does not access a SCSI device (logical unit). This utility accesses a library associated with this package. Amongst other things the library decodes SCSI sense data.

The sg_raw utility takes a ASCII hexadecimal sequence representing a SCSI CDB. When sg_raw is given the '-vvv' option, it will attempt to decode the CDB name.

Using the option combination: "--inhex=HFN --nodecode --write=WFN" may be used to convert hexadecimal (as produced by this and other utilities in this package) to binary where the output file is WFN.

Unlike many other utilities there is no --raw option. However binary data can be input using the --binary=BFN option while binary data can be output using the --write=WFN option (in the absence of the --hex option).

## EXAMPLES
Sense data is often printed out in kernel logs and sometimes on the command line when verbose or debug flags are given. It will be at least 8 bytes long, often 18 bytes long but may be longer. A sense data string might look like this:

f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00

00 00

Cut and paste it after the sg_decode_sense command:

sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00

and for this sense data the output should look like this:

Fixed format, current; Sense key: Medium Error

Additional sense: Unrecovered read error

Info fld=0x1234 [4660]

For a medium error the Info field is the logical block address (LBA) of the lowest numbered block that the associated SCSI command was not able to read (verify or write).

To convert arbitrary binary data to hex, suitable to be parsed by other sg3_utils utilities. The --nodecode option is used in this case:

sg_decode_sense -N -i vpd_zbdc.hex -w vpd_zbdc.bin

The '-HHH' will output hex to the console (stdout) in a form suitable for other utilities in this package to parse as input. And sg_decode_sense can also be used to convert from arbitrary hex to binary with:

sg_decode_sense -N -b vpd_zbdc.raw -HHH

Note that tools like hexdump and od place a counter (i.e. an index starting at 0) at the beginning of each line which is a pain when parsing hex. The '/-HHH' option(s) does not output that leading counter on each line.

## EXIT STATUS
The exit status of sg_decode_sense 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 © 2010-2022 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_requests,sg_raw(sg3_utils)

branch: sisyphus


title: sg_emc_trespass(8)

text:
# sg_emc_trespass(8)

## NAME
sg_emc_trespass - change ownership of SCSI LUN from another Service-Processor to this one

## SYNOPSIS
sg_emc_trespass [-d] [-hr] [-s] [-V] DEVICE

## DESCRIPTION
sg_emc_trespass sends an EMC-specific Trespass Command to the DEVICE with the selected options. This Mode Select changes the ownership of the LUN of the device from another Service-Processor to the one the command was received on.

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

-d

outputs some extra debug information associated with executing this command

-hr

Sets the 'Honor Reservation' bit in the command. If set, the trespass will only succeed to change the ownership from the Peer SP if the Peer SP does not have an outstanding SCSI reservation for the LUN. By default, the reservation state will be ignored.

-s

Send the short version of the trespass command instead of the long version. The short version is supported on the EMC FC5300, FC4500 and FC4700. The long version (default) is supported on the CLARiiON CX and AX family arrays.

-V

print out version string then exit.

In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices (e.g. SCSI disks and DVD drives) can also be specified. For example "sg_start 0 /dev/sda" will work in the 2.6 series kernels.

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

## AUTHOR
Written by Lars Marowsky-Bree, based on sg_start.

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

## COPYRIGHT
Copyright © 2004-2012 Lars Marowsky-Bree, Douglas Gilbert.

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


title: sg_format(8)

text:
# sg_format(8)

## NAME
sg_format - format, format with preset, resize SCSI disk; format tape

## SYNOPSIS
sg_format [--cappid] [--cmplst={0|1}] [--count=COUNT] [--dcrt] [--dry-run] [--early] [--ffmt=FFMT] [--fmtmaxlba [--format] [--help] [--ip-def] [--long] [--mode=MP] [--pfu=PFU] [--pie=PIE] [--pinfo] [--poll=PT] [--preset=ID] [--quick] [--resize] [--rto_req] [--security] [--six] [--size=LB_SZ] [--tape=FM] [--timeout=SECS] [--verbose] [--verify] [--version] [--wait] DEVICE

## DESCRIPTION
Not all SCSI direct access devices need to be formatted and some have vendor specific formatting procedures. SCSI disks with rotating media are probably the largest group that do support a 'standard' format operation. They are typically factory formatted to a block size of 512 bytes with the largest number of blocks that the manufacturer recommends. The manufacturer's recommendation typically leaves aside a certain number of tracks, spread across the media, for reassignment of blocks to logical block addresses during the life of the disk.

This utility issues one of three SCSI format commands: FORMAT UNIT, FORMAT MEDIUM or FORMAT WITH PRESET. In the following description, unqualified sections will usually be referring to the SCSI FORMAT UNIT command. Both FORMAT UNIT and FORMAT WITH PRESET apply to disks (or disk-like devices). The FORMAT MEDIUM command is for tapes. A SCSI INQUIRY response categorizes the 'Peripheral Device Type' (PDT) of each SCSI device. This utility uses the PDT to check if there is a conflict between the DEVICE and the given option (e.g. giving the --tape=FM option when DEVICE is a normal disk). If there is a conflict, this utility will not continue.

This utility can format modern SCSI disks and potentially change their block size (if permitted) and the block count (i.e. number of accessible blocks on the media also known as "resizing"). Resizing a disk to less than the manufacturer's recommended block count is sometimes called "short stroking" (see NOTES section). Resizing the block count while not changing the block size may not require a format operation. The SBC-2 standard (see www.t10.org) has obsoleted the "format device" mode page. Many of the low level details found in that mode page are now left up to the discretion of the manufacturer. There is a Format Status log page which reports on the previous successful format operation(s).

When this utility is used without options (i.e. it is only given a DEVICE argument) it prints out the existing block size and block count derived from two sources. These two sources are a block descriptor in the response to a MODE SENSE command and the response to a READ CAPACITY command. The reason for this double check is to detect a "format corrupt" state (see the NOTES section). This usage will not modify the disk.

When this utility is used with either --format, --preset=ID or --tape=FM, it will attempt to format the given DEVICE. In the absence of the --quick option there is a 15 second pause during which time the user is invited thrice (5 seconds apart) to abort sg_format. This occurs just prior the SCSI FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command being issued. See the NOTES section for more information.

Protection information (PI) is optional and is made up of one or more protection intervals, each made up of 8 bytes associated with a logical block. When PI is active each logical block will have 1, 2, 4, 8, etc protection intervals (i.e. a power of two), interleaved with (and following) the user data to which they refer. Four protection types are defined with protection type 0 being no protection intervals. See the PROTECTION INFORMATION section below for more information.

When the --tape=FM option is given then the SCSI FORMAT MEDIUM command is sent to the DEVICE. FORMAT MEDIUM is defined in the SSC documents at T10 and prepares a volume for use. That may include partitioning the medium. See the section below on TAPE for more information.

The FORMAT WITH PRESET was added in draft SBC-4 revision 18. A preset pattern, selected by the PRESET IDENTIFIER field (--id=FWPID), is written to the disk. See the FORMAT PRESETS VPD page (0xb8) for a list of available Format preset identifiers and their associated data.

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

-a, --cappid

this option sets the CAPPID bit in the MODE SELECT header which is part of that command's parameter list. A MODE SELECT command is needed when the COUNT (i.e. number of logical blocks) is being changed. The MODE SELECT command needs to complete successfully before FORMAT UNIT command is performed. The CAPPID bit (introduced in SBC-5 revision 4) is closely related to the Capacity/Product identification mapping VPD page (0xba). If that VPD page is not present, then the CAPPID bit is not set unless the option is given twice. If the CAPPID bit is not supported a sense key of illegal request with an additional sense of "invalid field in parameter list" should be reported.

If successful, this option may lead to the standard INQUIRY response Product identification field being changed. If so, a Unit attention condition is set with an additional sense of "Inquiry data has changed".

-C, --cmplst={0|1}

sets the CMPLST ("complete list") bit in the FORMAT UNIT cdb to 0 or 1. If the value is 0 then the existing GLIST (grown list) is taken into account. If the value is 1 then the existing GLIST is ignored. CMPLST defaults to 1 apart from when the --ffmt=FFMT option's value is non-zero in which case CMPLST defaults to 0. See the LISTS section below. In most cases this bit should be left at its default value.

-c, --count=COUNT

where COUNT is the number of blocks to be formatted or media to be resized to. Can be used with either --format or --resize. With --format this option need not be given in which case it is assumed to be zero.

With --format the interpretation of COUNT is:

(COUNT > 0) : only format the first COUNT blocks and READ CAPACITY will report COUNT blocks after format

(COUNT = 0) and block size unchanged : use existing block count

(COUNT = 0) and block size changed : recommended maximum block count for new block size

(COUNT = -1) : use recommended maximum block count

(COUNT < -1) : illegal With --resize this option must be given and COUNT has this interpretation:

(COUNT > 0) : after resize READ CAPACITY will report COUNT blocks

(COUNT = 0) : after resize READ CAPACITY will report 0 blocks

(COUNT = -1) : after resize READ CAPACITY will report its maximum number of blocks

(COUNT < -1) : illegal

In both cases if the given COUNT exceeds the maximum number of blocks (for the block size) then the disk reports an error. See NOTES section below.

-D, --dcrt

this option sets the DCRT bit in the FORMAT UNIT command's parameter list header. It will "disable certification". Certification verifies that blocks are usable during the format process. Using this option may speed the format but --ffmt=FFMT, if available, would probably be better. The default action of this utility (i.e. when this option is not given) is to clear the DCRT bit thereby requesting "media certification" (also unless another option needs it, the FOV bit will be cleared). When the DCRT bit is set, the FOV bit must also be set hence sg_format does that.

If this option is given twice then certification is enabled by clearing the DCRT bit and setting the FOV bit. Both these bits are found in the parameter list associated with the FORMAT UNIT cdb.

-d, --dry-run

this option will parse the command line, do all the preparation but bypass the actual FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command. Also if the options would otherwise cause the logical block size to change, then the MODE SELECT command that would do that is also bypassed when the dry run option is given.

-e, --early

during a format operation, The default action of this utility is to poll the disk every 60 seconds (or every 10 seconds if FFMT is non-zero) to determine the progress of the format operation until it is finished. When this option is given this utility will exit "early", that is as soon as the format operation has commenced. Then the user can monitor the progress of the ongoing format operation with other utilities (e.g. sg_turs(8) or sg_requests(8)). This option and --wait are mutually exclusive.

-t, --ffmt=FFMT

FFMT (fast format) is placed in a field of the same name in the FORMAT UNIT cdb. The field was introduced in SBC-4 revision 10. The default value is 0 which implies the former action which is typically to overwrite all blocks on the DEVICE. That can take a long time (e.g. with hard disks over 10 TB in size that can be days). With FFMT set that time may be reduced to minutes or less. So it is worth trying if it is available.

FFMT has values 1 and 2 for fast format with 3 being reserved currently. These two values include this description: "The device server initializes the medium ... without overwriting the medium (i.e. resources for managing medium access are initialized and the medium is not written)". The difference between 1 and 2 concerns read operations on LBAs to which no data has been written to, after the fast format. When FFMT is 1 the read operation should return "unspecified logical block data" and complete without error. When FFMT is 2 the read operation may yield check condition status with a sense key set to hardware error, medium error or command aborted. See draft SBC-4 revision 16 section 4.34 for more details.

-b, --fmtmaxlba

This option is only active if it is given together with the --preset=ID option. If so it sets the FMTMAXLBA field in the FORMAT WITH PRESET command.

-f, --fmtpinfo=FPI

sets the FMTPINFO field in the FORMAT UNIT cdb to a value between 0 and 3. The default value is 0. The FMTPINFO field from SBC-3 revision 16 is a 2 bit field (bits 7 and 6 of byte 1 in the cdb). Prior to that revision it was a single bit field (bit 7 of byte 1 in the cdb) and there was an accompanying bit called RTO_REQ (bit 6 of byte 1 in the cdb). The deprecated options "--pinfo" and "--rto-req" represent the older usage. This option should be used in their place. See the PROTECTION INFORMATION section below for more information.

-F, --format

issue one of the three SCSI "format" commands. In the absence of the --preset=ID and --tape=FM options, the SCSI FORMAT UNIT command is issued. These commands will destroy all the data held on the media. This option is required to change the block size of a disk. In the absence of the --quick option, the user is given a 15 second count down to ponder the wisdom of doing this, during which time control-C (amongst other Unix commands) can be used to kill this process before it does any damage.

When used three times (or more) the preliminary MODE SENSE and SELECT commands are bypassed, leaving only the initial INQUIRY and FORMAT UNIT commands. This is for emergency use (e.g. when the MODE SENSE/SELECT commands are not working) and cannot change the logical block size.

Host managed zoned devices (e.g. many zoned disks) have a different PDT compared to other disks but can still be formatted as if they were 'normal' disks.

See NOTES section for implementation details and EXAMPLES section for typical use.

-h, --help

print out the usage information then exit.

-I, --ip-def

sets the default Initialization Pattern. Some disks (SSDs) use this to flag that a format should fully provision (i.e. associate a physical block with every logical block). The same disks (SSDs) might thin provision if this option is not given. If this option is given then the --security option cannot be given. Also accepts --ip_def for this option.

-l, --long

the default action of this utility is to assume 32 bit logical block addresses. With 512 byte block size this permits more than 2 terabytes (almost 2 ** 41 bytes) on a single disk. This option selects commands and parameters that allow for 64 bit logical block addresses. Specifically this option sets the "longlba" flag in the MODE SENSE (10) command and uses READ CAPACITY (16) rather than READ CAPACITY (10). If this option is not given and READ CAPACITY (10) or MODE SELECT detects a disk the needs more than 32 bits to represent its logical blocks then it is set internally. This option does not set the LONGLIST bit in the FORMAT UNIT command. The LONGLIST bit is set as required depending other parameters (e.g. when '--pie=PIE' is greater than zero).

-M, --mode=MP

MP is a mode page number (0 to 62 inclusive) that will be used for reading and perhaps changing the device logical block size. The default is 1 which is the Read-Write Error Recovery mode page.

Preferably the chosen (or default) mode page should be saveable (i.e. accept the SP bit set in the MODE SELECT command used when the logical block size is being changed). Recent version of this utility will retry a MODE SELECT if the SP=1 variant fails with a sense key of ILLEGAL REQUEST. That retry will use the same MODE SELECT command but with SP=0 .

-P, --pfu=PFU

sets the "Protection Field Usage" field in the parameter block associated with a FORMAT UNIT command to PFU. The default value is 0, the only other defined value currently is 1. See the PROTECTION INFORMATION section below for more information.

-q, --pie=PIE

sets the "Protection Interval Exponent" field in the parameter block associated with a FORMAT UNIT command to PIE. The default value is 0. PIE can only be non-zero with protection types 2 and 3. The value of 0 is typical for 512 byte blocks; with 4096 byte blocks a value of 3 may be appropriate (i.e. 8 protection intervals interleaved with 4096 bytes of user data). A device may not support any non-zero values. This field first appeared in SBC-3 revision 18.

-p, --pinfo

this option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it sets bit 7 of byte 1 in the FORMAT UNIT cdb and that is equivalent to setting --fmtpinfo=2. [So if --pinfo is used (plus --fmtpinfo=FPI and --pfu=PFU are not given or their arguments are 0) then protection type 1 is selected.]

-x, --poll=PT

where PT is the type of poll used. If PT is 0 then a TEST UNIT READY command is used, otherwise a REQUEST SENSE command is used. The default is currently 0 but this will change to 1 in the near future. See the NOTES sections below.

-E, --preset=ID

this option instructs this utility to issue a SCSI FORMAT WITH PRESET command. The PRESET IDENTIFIER field in that cdb is set to ID. The IMMED field in that cdb is also set unless the --wait option is also given, in which case it is cleared.

-Q, --quick

the default action (i.e. when the option is not given) is to give the user 15 seconds to reconsider doing a format operation on the DEVICE. When this option is given that step (i.e. the 15 second warning period) is skipped.

-r, --resize

rather than format the disk, it can be resized. This means changing the number of blocks on the device reported by the READ CAPACITY command. This option should be used with the --count=COUNT option. The contents of all logical blocks on the media remain unchanged when this option is used. This means that any resize operation can be reversed. This option cannot be used together with either --format or a --size=LB_SZ whose argument is different to the existing block size.

-R, --rto_req

The option is deprecated, use the --fmtpinfo=FPI option instead. If used, then it sets bit 6 of byte 1 in the FORMAT UNIT cdb.

-S, --security

sets the "Security Initialization" (SI) bit in the FORMAT UNIT command's initialization pattern descriptor within the parameter list. According to SBC-3 the default initialization pattern "shall be written using a security erasure write technique". See the NOTES section on the SCSI SANITIZE command. If this option is given then the --ip_def option cannot be given.

-6, --six

Use 6 byte variants of MODE SENSE and MODE SELECT. The default action is to use the 10 byte variants. Some MO drives need this option set when doing a format.

-s, --size=LB_SZ

where LB_SZ is the logical block size (i.e. number of user bytes in each block) to format the device to. The default value is whatever is currently reported by the block descriptor in a MODE SENSE command. If the block size given by this option is different from the current value then a MODE SELECT command is used to change it prior to the FORMAT UNIT command being started (as recommended in the SBC standards). Some SCSI disks have 512 byte logical blocks by default and allow an alternate logical block size of 4096 bytes. If the given size in unacceptable to the disk, most likely an "Invalid field in parameter list" message will appear in sense data (requires the use of '-v' to decode sense data).

Note that formatting a disk to add or remove protection information is not regarded as a change to its logical block size so this option should not be used.

-T, --tape=FM

will send a FORMAT MEDIUM command to the DEVICE with its FORMAT field set to FM. This option is used to prepare a tape (i.e. the "medium") in a tape drive for use. Values for FM include 0 to do the "default" format; 1 to partition a volume and 2 to do a default format then partition.

-m, --timeout=SECS

where SECS is the FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command timeout in seconds. SECS will only be used if it exceeds the internal timeout which is 20 seconds if the IMMED bit is set and 72000 seconds (20 hours) or higher if the IMMED bit is not set. If the disk size exceeds 4 TB then the timeout value is increased to 144000 seconds (40 hours). And if it is greater than 8 TB then the timeout value is increased to 288000 seconds (80 hours). If the timeout is exceeded then the operating system will typically abort the command. Aborting a command may escalate to a LUN reset (or worse). A timeout may also leave the disk or tape format operation incomplete. And that may result in the disk or tape being in a "format corrupt" state requiring another format to remedy the situation. So for various reasons command timeouts are best avoided. An alternate long option form is --tmo=SECS.

-v, --verbose

increase the level of verbosity, (i.e. debug output). "-vvv" gives a lot more debug output.

-y, --verify

set the VERIFY bit in the FORMAT MEDIUM cdb. The default is that the VERIFY bit is clear. This option is only appropriate for tapes.

-V, --version

print the version string and then exit.

-w, --wait

the default format action is to set the "IMMED" bit in the FORMAT UNIT command's (short) parameter header. If this option (i.e. --wait) is given then the "IMMED" bit is not set. If --wait is given then the FORMAT UNIT, FORMAT WITH PRESET or FORMAT MEDIUM command waits until the format operation completes before returning its response. This can be many hours on large disks. See the --timeout=SECS option.

Alternatively this option may be useful when used together with --ffmt=FFMT (and FFMT greater than 0) since the fast format may only be a matter of seconds.

## LISTS
The SBC-3 draft (revision 20) defines PLIST, CLIST, DLIST and GLIST in section 4.10 on "Medium defects". Briefly, the PLIST is the "primary" list of manufacturer detected defects, the CLIST ("certification" list) contains those detected during the format operation, the DLIST is a list of defects that can be given to the format operation. The GLIST is the grown list which starts in the format process as CLIST+DLIST and can "grow" later due to automatic reallocation (see the ARRE and AWRE bits in the Read-Write Error Recovery mode page (see sdparm(8))) and use of the SCSI REASSIGN BLOCKS command (see sg_reassign(8)).

By the SBC-3 standard (following draft revision 36) the CLIST and DLIST had been removed, leaving PLIST and GLIST. Only PLIST and GLIST are found in the SBC-4 drafts.

The CMPLST bit (controlled by the --cmplst=0|1 option) determines whether the existing GLIST, when the format operation is invoked, is taken into account. The sg_format utility sets the FOV bit to zero which causes DPRY=0, so the PLIST is taken into account, and DCRT=0, so the CLIST is generated and used during the format process.

The sg_format utility does not permit a user to provide a defect list (i.e. DLIST).

## PROTECTION INFORMATION
Protection Information (PI) is additional information held with logical blocks so that an application and/or host bus adapter can check the correctness of those logical blocks. PI is placed in one or more protection intervals interleaved in each logical block. Each protection interval follows the user data to which it refers. A protection interval contains 8 bytes made up of a 2 byte "logical block guard" (CRC), a 2 byte "logical block application guard", and a 4 byte "logical block reference tag". Devices with 512 byte logical block size typically have one protection interval appended, making its logical block data 520 bytes long. Devices with 4096 byte logical block size often have 8 protection intervals spread across its logical block data for a total size of 4160 bytes. Note that for all other purposes the logical block size is considered to be 512 and 4096 bytes respectively.

The SBC-3 standard have added several "protection types" to the PI introduced in the SBC-2 standard. SBC-3 defines 4 protection types (types 0 to 3) with protection type 0 meaning no PI is maintained. While a device may support one or more protection types, it can only be formatted with 1 of the 4. To change a device's protection type, it must be re-formatted. For more information see the Protection Information in section 4.21 of draft SBC-4 revision 16.

A device that supports PI information (i.e. supports one or more protection types 1, 2 and 3) sets the "PROTECT" bit in its standard INQUIRY response. It also sets the SPT field in the EXTENDED INQUIRY VPD page response to indicate which protection types it supports. Given PROTECT=1 then SPT=0 implies the device supports PI type 1 only, SPT=1 implies the device supports PI types 1 and 2, and various other non-obvious mappings up to SPT=7 which implies protection types 1, 2 and 3 are supported. The current protection type of a disk can be found in the "P_TYPE" and "PROT_EN" fields in the response of a READ CAPACITY (16) command (e.g. with the 'sg_readcap --long' utility).

Given that a device supports a particular protection type, a user can then choose to format that disk with that protection type by setting the "FMTPINFO" and "Protection Field Usage" fields in the FORMAT UNIT command. Those fields correspond to the --fmtpinfo=FPI and the --pfu=PFU options in this utility. The list below shows the four protection types followed by the options of this utility needed to select them:

0 : --fmtpinfo=0 --pfu=0

1 : --fmtpinfo=2 --pfu=0

2 : --fmtpinfo=3 --pfu=0

3 : --fmtpinfo=3 --pfu=1

The default value of FPI (in --fmtpinfo=FPI) is 0 and the default value of PFU (in --pfu=PFU) is 0. So if neither --fmtpinfo=FPI nor --pfu=PFU are given then protection type 0 (i.e. no protection information) is chosen.

## NOTES
After a format that changes the logical block size or the number of logical blocks on a disk, the operating system may need to be told to re-initialize its setting for that disk. In Linux that can be done with:

echo 1 > /sys/block/sd{letter(s)}/device/rescan

where "letter(s)" will be between 'a' and 'zzz'. The lsscsi utility in Linux can be used to check the various namings of a disk.

The SBC-2 standard states that the REQUEST SENSE command should be used for obtaining progress indication when the format command is underway. However, tests on a selection of disks shows that TEST UNIT READY commands yield progress indications (but not REQUEST SENSE commands). So the current version of this utility defaults to using TEST UNIT READY commands to poll the disk to find out the progress of the format. The --poll=PT option has been added to control this.

When the --format, --preset=ID or --tape=FM option is given without the --wait option then the corresponding SCSI command is issued with the IMMED bit set which causes the SCSI command to return after it has started the format operation. The --early option will cause sg_format to exit at that point. Otherwise the DEVICE is polled every 60 seconds or every 10 seconds if FFMT is non-zero. The poll is with TEST UNIT READY or REQUEST SENSE commands until one reports an "all clear" (i.e. the format operation has completed). Normally these polling commands will result in a progress indicator (expressed as a percentage) being output to the screen. If the user gets bored watching the progress report then sg_format process can be terminated (e.g. with control-C) without affecting the format operation which continues. However a target or device reset (or a power cycle) will probably cause the format to cease and the DEVICE to become "format corrupt".

When the --format (--preset=ID or --tape) and --wait options are both given then this utility may take a long time to return. In this case care should be taken not to send any other SCSI commands to the disk as it may not respond leaving those commands queued behind the active format command. This may cause a timeout in the OS driver (in a lot shorter period than 20 hours applicable to some format operations). This may result in the OS resetting the disk leaving the format operation incomplete. This may leave the disk in a "format corrupt" state requiring another format to remedy the situation. Modern SCSI devices should yield a "not ready" sense key with an additional sense indicating a format is in progress. With older devices the user should take precautions that nothing attempts to access a device while it is being formatted. Unmounting in mounted file systems on a DEVICE prior to calling this utility is strongly advised.

When the block size (i.e. the number of bytes in each block) is changed on a disk two SCSI commands must be sent: a MODE SELECT to change the block size followed by a FORMAT command. If the MODE SELECT command succeeds and the FORMAT fails then the disk may be in a state that the standard calls "format corrupt". A block descriptor in a subsequent MODE SENSE will report the requested new block size while a READ CAPACITY command will report the existing (i.e. previous) block size. Alternatively the READ CAPACITY command may fail, reporting the device is not ready, potentially requiring a format. The solution to this situation is to do a format again (and this time the new block size does not have to be given) or change the block size back to the original size.

The SBC-2 standard states that the block count can be set back to the manufacturer's maximum recommended value in a format or resize operation. This can be done by placing an address of 0xffffffff (or the 64 bit equivalent) in the appropriate block descriptor field to a MODE SELECT command. In signed (two's complement) arithmetic that value corresponds to '-1'. So a --count=-1 causes the block count to be set back to the manufacturer's maximum recommended value. To see exactly which SCSI commands are being executed and parameters passed add the "-vvv" option to the sg_format command line.

The FMTDATA field shown in the FORMAT UNIT cdb does not have a corresponding option in this utility. When set in the cdb it indicates an additional parameter list will be sent to the DEVICE along with the cdb. It is set as required, basically when any field in the parameter list header is set.

Short stroking is a technique to trade off capacity for performance on hard disks. "Hard" disk is often used to mean a storage device with spinning platters which contain the user data. Solid State Disk (SSD) is the newer form of storage device that contains no moving parts. Hard disk performance is usually highest on the outer tracks (usually the lower logical block addresses) so by resizing or reformatting a disk to a smaller capacity, average performance will usually be increased.

Other utilities may be useful in finding information associated with formatting. These include sg_inq(8) to fetch standard INQUIRY information (e.g. the PROTECT bit) and to fetch the EXTENDED INQUIRY VPD page (e.g. RTO and GRD_CHK bits). The sdparm(8) utility can be used to access and potentially change the now obsolete format mode page.

scsiformat is another utility available for formatting SCSI disks with Linux. It dates from 1997 (most recent update) and may be useful for disks whose firmware is of that vintage.

The COUNT numeric argument may include a multiplicative suffix or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section in the sg3_utils(8) man page.

The SCSI SANITIZE command was introduced in SBC-3 revision 27. It is closely related to the ATA sanitize disk feature set and can be used to remove all existing data from a disk. Sanitize is more likely to be implemented on modern disks (including SSDs) than FORMAT UNIT's security initialization feature (see the --security option) and in some cases much faster.

SSDs that support thin provisioning will typically unmap all logical blocks during a format. The reason is to improve the SSD's endurance. Also thin provisioned formats typically complete faster than fully provisioned ones on the same disk (see the --ip_def option). In either case format operations on SSDs tend to be a lot faster than they are on hard disks with spinning media.

Host managed zoned devices (aka zoned disks) have a different Peripheral Device Type [PDT=20 or 0x14] from normal disks. They can be considered as a superset of normal disks (e.g. SSDs and hard disks) at least from the perspective of the number of SCSI commands they support. Typically they can be formatted just like other SCSI disks. They have their own T10 standards: ZBC standard (INCITS 536-2016) and draft ZBC-2.

Two other zoned disk variants ("host aware" and "Domains and Realms") use the same PDT as other disks (i.e. PDT=0) and can be formatted by this utility as if they were normal disks.

## TAPE
Tape system use a variant of the FORMAT UNIT command used on disks. Tape systems use the FORMAT MEDIUM command which is simpler with only three fields in the cdb typically used. Apart from sharing the same opcode the cdbs of FORMAT UNIT and FORMAT MEDIUM are quite different. FORMAT MEDIUM's fields are VERIFY, IMMED and FORMAT (with TRANSFER LENGTH always set to 0). The VERIFY bit field is set with the --verify option. The IMMED bit is manipulated by the --wait option in the same way it is for disks; one difference is that if the --poll=PT option is not given then it defaults to PT of 1 which means the poll is done with REQUEST SENSE commands.

The argument given to the --tape=FM option is used to set the FORMAT field. FM can take values from "-1" to "15" where "-1" (the default) means don't do a tape format; value "8" to "15" are for vendor specific formats. The --early option may also be used to set the IMMED bit and then exit this utility (rather than poll periodically until it is finished). In this case the tape drive will still be busy doing the format for some time but, according to T10, should still respond in full to the INQUIRY and REPORT LUNS commands. Other commands (including REQUEST SENSE) should yield a "not ready" sense key with an additional sense code of "Logical unit not ready, format in progress". Additionally REQUEST SENSE should contain a progress indication in its sense data.

When FM is 1 or 2 then the settings in the Medium partition mode page control the partitioning. That mode page can be viewed and modified with the sdparm utility.

Prior to invoking this utility the tape may need to be positioned to the beginning of partition 0. In Linux that can typically be done with the mt utility (e.g. 'mt -f /dev/st0 rewind').

## EXAMPLES
These examples use Linux device names. For suitable device names in other supported Operating Systems see the sg3_utils(8) man page.

In the first example below simply find out the existing block count and size derived from two sources: a block descriptor in a MODE SELECT command response and from the response of a READ CAPACITY commands. No changes are made:

\# sg_format /dev/sdm

Now a simple format, leaving the block count and size as they were previously. The FORMAT UNIT command is executed in IMMED mode and the device is polled every 60 seconds to print out a progress indication:

\# sg_format --format /dev/sdm

Now the same format, but waiting (passively) until the format operation is complete:

\# sg_format --format --wait /dev/sdm

Next is a format in which the block size is changed to 520 bytes and the block count is set to the manufacturer's maximum value (for that block size). Note, not all disks support changing the block size:

\# sg_format --format --size=520 /dev/sdm

Now a resize operation so that only the first 0x10000 (65536) blocks on a disk are accessible. The remaining blocks remain unaltered.

\# sg_format --resize --count=0x10000 /dev/sdm

Now resize the disk back to its normal (maximum) block count:

\# sg_format --resize --count=-1 /dev/sdm

One reason to format a SCSI disk is to add protection information. First check which protection types are supported by a disk (by checking the SPT field in the Extended inquiry VPD page together with the Protect bit in the standard inquiry response):

\# sg_vpd -p ei -l /dev/sdb

extended INQUIRY data VPD page:

ACTIVATE_MICROCODE=0

SPT=1 [protection types 1 and 2 supported]

....

Format with type 1 protection:

\# sg_format --format --fmtpinfo=2 /dev/sdm

After a successful format with type 1 protection, READ CAPACITY(16) should show something like this:

\# sg_readcap -l /dev/sdm

Read Capacity results:

Protection: prot_en=1, p_type=0, p_i_exponent=0 [type 1 protection]

Logical block provisioning: lbpme=0, lbprz=0

....

To format with type 3 protection:

\# sg_format --format --fmtpinfo=3 --pfu=1 /dev/sdm

For the disk shown above this will probably fail because the Extended inquiry VPD page showed only types 1 and 2 protection are supported.

Here are examples of using fast format (FFMT field in FORMAT UNIT cdb) to quickly switch between 512 and 4096 byte logical block size. Assume disk starts with 4096 byte logical block size and all important data has been backed up.

\# sg_format --format --ffmt=1 --size=512 /dev/sdd

Now /dev/sdd should have 512 byte logical block size. And to switch it back:

\# sg_format --format --ffmt=1 --size=4096 /dev/sdd

Since fast formats can be very quick (a matter of seconds) using the --wait option may be appropriate.

And to use the Format with preset command this invocation could be used:

\# sg_format --preset=1 --fmtmaxlba /dev/sdd

The FORMAT PRESETS VPD page (0xb8) should be consulted to check that Preset identifier 0x1 is there and has the expected format (i.e. "default host aware zoned block device model with 512 bytes of user data in each logical block"). That VPD page can be viewed with the sg_vpd utility.

## EXIT STATUS
The exit status of sg_format is 0 when it is successful. Otherwise see the sg3_utils(8) man page. Unless the --wait option is given, the exit status may not reflect the success of otherwise of the format. Using sg_turs(8) and sg_readcap(8) after the format operation may be wise.

The Unix convention is that "no news is good news" but that can be a bit unnerving after an operation like format, especially if it finishes quickly (i.e. before the first progress poll is sent). Giving the --verbose option once should supply enough additional output to settle those nerves.

## AUTHORS
Written by Grant Grundler, James Bottomley and Douglas Gilbert.

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

## COPYRIGHT
Copyright © 2005-2023 Grant Grundler, James Bottomley and Douglas Gilbert

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

## SEE ALSO
sg_turs(8), sg_requests(8), sg_inq(8), sg_modes(8), sg_vpd(8), sg_reassign(8), sg_readcap(8), sg3_utils(8), sg_sanitize(8) [all in sg3_utils], lsscsi(8), mt(mt-st), sdparm(8), scsiformat (old), hdparm(8)


title: sg_get_config(8)

summary: send SCSI GET CONFIGURATION command (MMC\-4 +)

text:
# sg_get_config(8)

## NAME
sg_get_config - send SCSI GET CONFIGURATION command (MMC-4 +)

## SYNOPSIS
sg_get_config [--brief] [--current] [--help] [--hex] [--inner-hex] [--list] [--raw] [--readonly] [--rt=RT] [--starting=FC] [--verbose] [--version] DEVICE

## DESCRIPTION
Sends a SCSI GET CONFIGURATION command to DEVICE and decodes the response. The response includes the features and profiles of the device. Typically these devices are CD, DVD, HD-DVD and BD players that may (but not necessarily) have media in them. These devices may well be connected via ATAPI, USB or IEEE 1394 transports. In such cases they are "SCSI" devices only in the sense that they use the "Multi-Media command" set (MMC). MMC is a specialized SCSI command set whose definition can be found at https://www.t10.org .

This utility is based on the MMC-4 and later draft standards. See section 5 on "Features and Profile for Multi_Media devices" for more information on specific feature parameters and profiles. The manufacturer's product manual may also be useful.

Since modern DVD and BD writers support many features and profiles, the decoded output from this utility can be large. There are various ways to cut down the output. If the --brief option is used only the feature names are shown and the feature parameters are not decoded. Alternatively if only one feature is of interest then this combination of options is appropriate: "--rt=2 --starting=FC". Another possibility is to show only the features that are relevant to the media in the drive (i.e. "current") with the "--rt=1" option.

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

-b, --brief

show the feature names but don't decode the parameters of those features. When used with --list outputs known feature names but not known profile names.

-c, --current

output features marked as current. This option is equivalent to '--rt=1'.

-h, --help

output the usage message then exit.

-H, --hex

output the response in hex (don't decode response).

-i, --inner-hex

decode to the feature name level then output each feature's data in hex.

-l, --list

list all known feature and profile names. Ignore the device name (if given). Simply lists the feature names and profiles (followed by their hex values) that this utility knows about. If --brief is also given then only feature names are listed.

-q, --readonly

opens the DEVICE read-only rather than read-write which is the default. The Linux sg driver needs read-write access for the SCSI GET CONFIGURATION command but other access methods may require read-only access.

-r, --rt=RT

where RT is the field of that name in the GET CONFIGURATION cdb. Allowable values are 0, 1, 2, or 3 . The command's action also depends on the value given to the --starting=FC option. The default value is 0. When RT is 0 then all features, regardless of currency, are returned (whose feature code is greater than or equal to FC given to --starting=). When RT is 1 then all current features are returned (whose feature code is greater than or equal to FC). When RT is 2 then the feature whose feature code is equal to FC, if any, is returned. When RT is 3 the response is reserved (probably yields an "illegal field in cdb" error). To simplify the meanings of the RT values are:

0 : all features, current on not

1 : only current features

2 : only feature whose code is FC

3 : reserved

-R, --raw

output response in binary (to stdout). Note that the short form is -R unlike most other utilities in this package that use -r for this action.

-s, --starting=FC

where FC is the feature code value. This option works closely with the --rt=RT option. The FC value is in the range 0 to 65535 (0xffff) inclusive. Its default value is 0. A value prefixed with "0x" (or a trailing 'h') is interpreted as hexadecimal.

-v, --verbose

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

-V, --version

print the version string and then exit.

## NOTES
There are multiple versions of the MMC (draft) standards: MMC [1997], MMC-2 [2000], MMC-3 [2002], MMC-4 and MMC-5. The first three are now ANSI INCITS standards with the year they became standards shown in brackets. The draft immediately prior to standardization can be found at https://www.t10.org . In the initial MMC standard there was no GET CONFIGURATION command and the relevant information was obtained from the "CD capabilities and mechanical status mode page" (mode page 0x2a). It was later renamed the "MM capabilities and mechanical status mode page" and has been made obsolete in MMC-4 and MMC-5. The GET CONFIGURATION command was introduced in MMC-2 and has become a replacement for that mode page. New features such as support for "BD" (blue ray) media type can only be found by using the GET CONFIGURATION command. Hence older CD players may not support the GET CONFIGURATION command in which case the "MM capabilities ..." mode page can be checked with sdparm(8), sginfo(8) or sg_modes(8).

In the 2.4 series of Linux kernels the DEVICE must be a SCSI generic (sg) device. In the 2.6 series block devices can also be specified. For example "sg_get_config /dev/hdc" will work in the 2.6 series kernels as long as /dev/hdc is an ATAPI device. In the 2.6 series external DVD writers attached via USB could be queried with "sg_get_config /dev/scd1" for example.

## EXIT STATUS
The exit status of sg_get_config 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 © 2004-2012 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
sginfo(8), sg_modes(8), sg_inq(8), sg_prevent(8), sg_start(8) [all in sg3_utils], sdparm(8)


title: sg_get_elem_status(8)

text:
# sg_get_elem_status(8)

## NAME
sg_get_elem_status - send SCSI GET PHYSICAL ELEMENT STATUS command

## SYNOPSIS
sg_get_elem_status [--brief] [--filter=FLT] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--js-file=JFN] [--maxlen=LEN] [--raw] [--readonly] [--report-type=RT] [--starting=ELEM] [--verbose] [--version] DEVICE

## DESCRIPTION
Send the SCSI GET PHYSICAL ELEMENT STATUS command to the DEVICE and output the response. That command was introduced in (draft) SBC-4 revision 16.

T10 drafts now speak of both 'physical' and 'storage' elements. The latter term is more specific (i.e. storage elements are a sub-set of physical elements) and refers to disk resources that control user data storage. An example of a storage element is the user data associated with a head on a spinning hard disk. When a storage element has been "depopulated" its former storage accessed via LBAs is no longer available. Physical elements are more general and includes storage elements and might include disk resources used for "saved" mode page settings amongst other things.

The default action of this utility is to decode the response into a header and up to 32 physical element status descriptors. The status descriptors are output one per line. The amount of output can be reduced by the --brief option.

Rather than send this SCSI command to DEVICE, if the --inhex=FN option is given, then the contents of the file named FN are decoded as ASCII hex (or binary if --raw is also given) and then processed as if it was the response of the GET PHYSICAL ELEMENT STATUS command.

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

-b, --brief

when used once, the output of each physical element status descriptor is reduced to: <element_id>: <element_type>,<element_health> . All three are output as decimal integers. When used twice the "Element descriptors:" line introducing the status descriptors is not output. When used three or more times only the response header is output.

-f, --filter=FLT

where FLT is placed in a two bit field called FILTER in the GET PHYSICAL ELEMENT STATUS command. Only two values are defined for that field: 0 for all element descriptors; 1 for those element descriptors that are outside 'spec' or have depopulation information to report. In both cases the REPORT TYPE and STARTING ELEMENT fields may further restrict (reduce) the number of element descriptors returned. The default value is zero.

-h, --help

output the usage message then exit.

-H, --hex

output response to this command in ASCII hex. Each line of 16 bytes is preceded by an address or index, starting at 0 and the address is also in hex. If given twice then an ASCII rendering of each byte is appended to the line output. If given three or more times then only the ASCII hex of each byte is output, 16 bytes per line (i.e. so no leading address nor trailing ASCII rendering). This latter form is suitable for placing in a file and being used with the --inhex=FN option in a later invocation.

-i, --inhex=FN

where FN is a file name whose contents are assumed to be ASCII hexadecimal. If DEVICE is also given then DEVICE is ignored, a warning is issued and the utility continues, decoding the file named FN. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more information. If the --raw option is also given then the contents of FN are treated as binary.

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

output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=".

See sg3_utils_json manpage or use '?' for JO to get a summary.

-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

where LEN is the (maximum) response length in bytes. It is placed in the cdb's "allocation length" field. If not given then 1056 is used. 1056 is enough space for the response header plus 32 physical element status descriptors. LEN should be a multiple of 32 (e.g. 32, 64, and 96 are suitable).

-r, --raw

output response in binary (to stdout) unless the --inhex=FN option is also given. In that case the input file name (FN) is decoded as binary (and the output is _not_ in binary).

-R, --readonly

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

-t, --report-type=RT

where RT will be placed in the REPORT TYPE field of the GET PHYSICAL ELEMENT STATUS command. Currently only two values are defined: 0 for 'physical element' and 1: for 'storage element'. The default value is 0 .

-s, --starting=ELEM

where ELEM is placed in the STARTING ELEMENT field of the GET PHYSICAL ELEMENT STATUS command. Only physical elements with identifiers greater than, or equal to ELEM are returned. The default value is zero which, while it isn't a valid element identifier (since they must be non-zero), is given in an example in Annex L of SBC-4 revision 17. So an ELEM of zero is assumed to be valid in this context.

-v, --verbose

increase the level of verbosity, (i.e. debug output). Additional output caused by this option is sent to stderr.

-V, --version

print the version string and then exit.

## NOTES
The "Warning - physical element status change" additional sense code [0xb, 0x14] is special and should prompt an application client to call the GET PHYSICAL ELEMENT STATUS command. How this warning is triggered depends on the settings in the Informational Exceptions Control mode page [0xc, 0x0].

After detecting one or more out-of-spec storage elements the disk in question should either be decommissioned or have the REMOVE ELEMENT AND TRUNCATE (or ... AND MODIFY ZONES) command invoked to repair (and reduce the storage capacity) of the disk.

## EXIT STATUS
The exit status of sg_get_elem_status 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 © 2019-2022 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_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils)


title: sg_get_lba_status(8)

text:
# sg_get_lba_status(8)

## NAME
sg_get_lba_status - send SCSI GET LBA STATUS(16 or 32) command

## SYNOPSIS
sg_get_lba_status [--16] [--32] [--blockhex] [--brief] [--element-id=EI] [--help] [--hex] [--inhex=FN] [--json[=JO]] [--lba=LBA] [--maxlen=LEN] [--raw] [--readonly] [--report-type=RT] [--scan-len=SL] [--verbose] [--version] DEVICE

## DESCRIPTION
Send the SCSI GET LBA STATUS(16) or GET LBA STATUS(32) command to the DEVICE and output the response. The 16 byte command variant was introduced in (draft) SBC-3 revision 20 and devices that support logical block provisioning should support this command. The GET LBA STATUS(32) command was added in (draft) SBC-4 revision 14.

The default action is to decode the response into one LBA status descriptor per line then output a header and the status descriptors to stdout. The descriptor LBA is output in hex (prefixed by '0x') and the number of blocks is output in decimal followed by the provisioning status, LBA accessibility and additional status in decimal. The provisioning status can be in the range 0 to 15 of which only 0 (mapped or unknown), 1 (unmapped), 2 (anchored), 3 (mapped) and 4 (unknown) are used currently. The amount of output can be reduced by the --brief option.

Rather than send this SCSI command to DEVICE, if the --inhex=FN option is given, then the contents of the file named FN are decoded as ASCII hex and then processed if it was the response of this command.

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

-S, --16

send SCSI GET LBA STATUS(16) command which is the 16 byte variant. In the absence of the --16 or the --32 options the SCSI GET LBA STATUS(16) command is sent. If both --16 and the --32 options are given then the GET LBA STATUS(16) command is sent.

-T, --32

send SCSI GET LBA STATUS(32) command which is the 32 byte variant. When given together with the --16 option then this option is ignored (so the GET LBA STATUS(16) command is sent).

-b, --brief

when use once then one LBA status descriptor per line is output to stdout. Each line has this format: "0x<descriptor_LBA> 0x<blocks> <provisioning_status> <additional_status>". So the descriptor's starting LBA and number of blocks are output in hex while the provisioning status and additional status are in decimal. When used twice (e.g. '-bb' or '--brief --brief') then the provisioning status of the given LBA (or LBA 0 if the --lba option is not given) is output to stdout. A check is made that the given LBA lies in the range of the first returned LBA status descriptor (as it should according to SBC-3 revision 20) and warnings are sent to stderr if it doesn't.

-B, --blockhex

the number of blocks in each LBA status descriptor is usually displayed in decimal. An exception is when the --brief option is given in which case it is shown in hexadecimal. When the option is given once, both cases are output in hexadecimal. When the option is given twice, both cases are output in decimal.

-e, --element-id=EI

where EI is the element identifier of the physical element for which the LBAs shall be reported based on the value in the report type field (i.e. RT). This option is only active with the SCSI GET LBA STATUS(32) command (i.e. it is ignored if the GET LBA STATUS(16) command is sent).

Valid element identifiers are non-zero. The default value of EI is 0 which means in the context that no element identifier is specified.

-h, --help

output the usage message then exit.

-H, --hex

output response to this command in ASCII hex. To produce hex output suitable for a later invocation to fetch with the --inhex=FN option, use this option three times. The short form option makes this more convenient: '-HHH'.

-i, --inhex=FN

where FN is a filename whose contents are assumed to be ASCII hexadecimal bytes. See the "HEX, BINARY AND JSON FORMATS" section in the sg3_utils manpage for more information. If DEVICE is also given then it is ignored. If the --raw option is also given then the contents of FN are treated as binary.

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

output is in JSON format instead of plain text form. Note that arguments to the short and long form are themselves optional and if present start with "=" and no whitespace is permitted around that "=".

See sg3_utils_json manpage or use '?' for JO to get a summary.

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

-l, --lba=LBA

where LBA is the starting Logical Block Address (LBA) to check the provisioning status for. Note that the DEVICE chooses how many following blocks that it will return provisioning status for.

-m, --maxlen=LEN

where LEN is the (maximum) response length in bytes. It is placed in the cdb's "allocation length" field. If not given then 24 is used. 24 is enough space for the response header and one LBA status descriptor. LEN should be 8 plus a multiple of 16 (e.g. 24, 40, and 56 are suitable).

-r, --raw

output response in binary (to stdout) unless the --inhex=FN option is also given. In that case the input file name (FN) is decoded as binary (and the output is _not_ in binary).

-R, --readonly

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

-t, --report-type=RT

where RT is 0 for report all LBAs; 1 for report LBAs using non-zero provisioning status; 2 for report LBAs that are mapped; 3 for report LBAs that are de-allocated; 4 for report LBAs that are anchored; 16 for report LBAs that may return an unrecovered error. The REPORT TYPE field was added to the GET LBA STATUS cdb in sbc4r12.

Since the REPORT TYPE field is newer than the command, the response contains the RTP bit to indicate whether or not the DEVICE acts on the REPORT TYPE field (set when it does act on it, clear otherwise).

-s, --scan-len=SL

where SL is the scan length which is the maximum number of contiguous logical blocks to be scanned for logical blocks that meet the given report type (i.e. RT). This option is only active with the SCSI GET LBA STATUS(32) command (i.e. it is ignored if the GET LBA STATUS(16) command is sent).

The default value of SL is 0 which should be interpreted by the DEVICE as there is no limits to the number of LBAs that shall be scanned.

-v, --verbose

increase the level of verbosity, (i.e. debug output). Additional output caused by this option is sent to stderr.

-V, --version

print the version string and then exit.

## NOTES
In SBC-3 revision 25 the calculation associated with the Parameter Data Length field in the response was modified. Prior to that the byte offset was 8 and in revision 25 it was changed to 4.

For a discussion of logical block provisioning see section 4.7 of sbc4r14.pdf at https://www.t10.org (or the corresponding section of a later draft).

## EXAMPLES
This example uses a "canned" hex file rather than a real DEVICE.

\# cd <folder at root of sg3_utils source package>

\# sg_get_lba_status --inhex=inhex/get_lba_status.hex

Command completed due to meeting capacity of medium

RTP=0x0

[1] LBA: 0x0 blocks: 287453952 mapped (or unknown); LBA accessibility not reported

[2] LBA: 0x11223300 blocks: 68 deallocated; LBA access not reported [may contain unrecovered errors]

[3] LBA: 0x11223344 blocks: 51 deallocated; LBA extent inaccessible [may contain unrecovered errors]

## EXIT STATUS
The exit status of sg_get_lba_status 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 © 2009-2022 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_write_same,sg_unmap,sg3_utils,sg3_utils_json(sg3_utils)