path: root/doc/sg_write_x.8

.TH SG_WRITE_X "8" "November 2017" "sg3_utils\-1.43" SG3_UTILS
.SH NAME
sg_write_x \- SCSI WRITE normal/ATOMIC/SAME/SCATTERED/STREAM, ORWRITE commands
.SH SYNOPSIS
.B sg_write_x
[\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app-\tag=AT\fR] [\fI\-\-atomic=AB\fR]
[\fI\-\-bmop=OP,PGP\fR] [\fI\-\-bs=LBS\fR] [\fI\-\-combined=DOF\fR]
[\fI\-\-dld=DLD\fR] [\fI\-\-dpo\fR] [\fI\-\-dry\-run\fR] [\fI\-\-fua\fR]
[\fI\-\-generation=EOG,NOG\fR] [\fI\-\-grpnum=GN\fR] [\fI\-\-help\fR]
\fI\-\-in=IF\fR [\fI\-\-lba=LBA[,LBA...]\fR] [\fI\-\-normal\fR]
[\fI\-\-num=NUM[,NUM...]\fR] [\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-or\fR]
[\fI\-\-raw\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-same=NDOB\fR]
[\fI\-\-scat\-file=SF\fR] [\fI\-\-scattered=RD\fR] [\fI\-\-stream=ID\fR]
[\fI\-\-strict\fR] [\fI\-\-tag\-mask=TM\fR] [\fI\-\-timeout=TO\fR]
[\fI\-\-unmap=U_A\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR]
[\fI\-\-wrprotect=WPR\fR] \fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-normal\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app\-tag=AT\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dld=DLD\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR]
[\fI\-\-grpnum=GN\fR] \fI\-\-in=IF\fR [\fI\-\-lba=LBA\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-strict\fR]
[\fI\-\-tag\-mask=TM\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-wrprotect=WPR\fR]
\fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-or\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-bmop=OP,PGP\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR] [\fI\-\-grpnum=GN\fR]
\fI\-\-in=IF\fR [\fI\-\-lba=LBA\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-strict\fR] [\fI\-\-timeout=TO\fR]
[\fI\-\-wrprotect=OPR\fR] \fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-atomic=AB\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app-tag=AT\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR] [\fI\-\-grpnum=GN\fR]
\fI\-\-in=IF\fR [\fI\-\-lba=LBA\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-strict\fR]
[\fI\-\-timeout=TO\fR] [\fI\-\-wrprotect=OPR\fR] \fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-same=NDOB\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app-tag=AT\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR] [\fI\-\-grpnum=GN\fR]
[\fI\-\-in=IF\fR] [\fI\-\-lba=LBA\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-strict\fR]
[\fI\-\-timeout=TO\fR] [\fI\-\-unmap=U_A\fR]
[\fI\-\-wrprotect=OPR\fR] \fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-scattered=RD\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app-tag=AT\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dld=DLD\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR]
[\fI\-\-grpnum=GN\fR] \fI\-\-in=IF\fR [\fI\-\-lba=LBA[,LBA...]\fR]
[\fI\-\-num=NUM[,NUM...]\fR] [\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-raw\fR]
[\fI\-\-ref\-tag=RT\fR] [\fI\-\-scat\-file=SF\fR] [\fI\-\-strict\fR]
[\fI\-\-tag\-mask=TM\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-wrprotect=WPR\fR]
\fIDEVICE\fR
.PP
.B sg_write_x
\fI\-\-stream=ID\fR [\fI\-\-16\fR] [\fI\-\-32\fR] [\fI\-\-app-tag=AT\fR]
[\fI\-\-bs=LBS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR] [\fI\-\-grpnum=GN\fR]
\fI\-\-in=IF\fR [\fI\-\-lba=LBA\fR] [\fI\-\-num=NUM\fR]
[\fI\-\-offset=OFF[,DLEN]\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-strict\fR]
[\fI\-\-tag\-mask=TM\fR] [\fI\-\-timeout=TO\fR] [\fI\-\-wrprotect=WPR\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
This utility will send one of six SCSI commands, all associated with writing
data to the given \fIDEVICE\fR. They are a "normal" WRITE, ORWRITE, WRITE
ATOMIC, WRITE SAME, WRITE SCATTERED or WRITE STREAM. This utility supports
the 16 and 32 byte variants of all six commands. Hence some closely related
commands are not supported (e.g. WRITE(10)). All 32 byte variants, apart from
ORWRITE(32), require the \fIDEVICE\fR to be formatted with type 1, 2 or 3
protection information (PI), making all logical blocks 8 bytes longer on the
media.
.PP
The command line interface is a little crowded with over thirty options. Hence
the SYNOPSIS, after listing all the (long) options, lists those applicable
to each supported command. For each command synopsis, the option that selects
the SCSI command is shown first. If no command option is given then a "normal"
WRITE is assumed. Even though the \fI\-\-scat\-file=SF\fR option can be
given for every command, it is only shown for WRITE SCATTERED where it is
most useful. If the \fI\-\-scat\-file=SF\fR option is given then neither the
\fI\-\-lba=LBA[,LBA...]\fR nor the \fI\-\-num=NUM[,NUM...]\fR options
should be given. Only the first item of the \fI\-\-lba=LBA[,LBA...]\fR and
the \fI\-\-num=NUM[,NUM...]\fR options (or first pair (or quintet) from the
\fI\-\-scat\-file=SF\fR option) is used for all but the WRITE SCATTERED
command. All commands can take \fI\-\-dry\-run\fR and \fI\-\-verbose\fR in
addition to those shown in the SYNOPSIS.
.PP
The logical block size in bytes can be given explicitly with the
\fI\-\-bs=LBS\fR option, as long as \fILBS\fR is greater than zero. It
is typically a power of tw0, 512 or greater. If the \fI\-\-bs=LBS\fR option
is not given or \fILBS\fR is zero then the SCSI READ CAPACITY command is
used to find the logical block size. First the READ CAPACITY(16) command is
tried and if successful the logical block size in the response is typically
used as the actual block size for this utility. The exception is when
PROT_EN is set in the response and the \fI\-\-wrprotect=WPR\fR option is
given and non\-zero; in which case 8 (bytes) is added to the logical block
size to yield the actual block size used by this utility. If READ
CAPACITY(16) fails then READ CAPACITY(10) is tried and if that works then
the logical block size in the response is used as the actual block size.
.PP
The number of bytes this utility will attempt to read from the file named by
\fIIF\fR is the product of the actual block size and the number of
blocks (\fINUM\fR or the sum of \fINUM\fR arguments). If less bytes are read
from the file \fIIF\fR and the \fI\-\-strict\fR option is given then this
utility exits at this point with an exit status of SG_LIB_FILE_ERROR. If less
bytes are read from the file \fIIF\fR and the \fI\-\-strict\fR option is not
given then zero bytes are substituted for the "missing" bytes and this
utility continues.
.PP
Attempts to write multi megabyte data with a single command are likely to fail
for one of several reasons. First the operating system might object to
allocating a buffer that large. Next the SCSI pass\-through usually limits
data blocks to a few megabytes or less. Finally the storage device might
have a limited amount of RAM to support an write operation such as atomic (as
it may need to roll back). The storage device can inform the application
client of its limitations via the block limits VPD page (0xb0), with the
maximum atomic transfer length field amongst others.
.PP
A degenerate LBA range descriptor with no PI has an LBA and NUM of zero.
A degenerate LBA range descriptor with PI additionally has its RT, AT and
TM fields set to zero. They are degenerate in the sense that they are
indistinguishable from a pad of zeros that follow the scatter list in the
data\-out buffer. SBC\-4 makes clear that the degenerate LBA range descriptor
is valid. This may become an issue if \fIRD\fR given in the
\fI\-\-scattered=RD\fR option has the value 0. In this case the logic may
need to scan the user provided data to calculate the number of LBA
range descriptors which is required by the WRITE SCATTERED cdb. In the
absence of other information the logic will take a degenerate LBA range
descriptor as a terminator of the scatter list.
.PP
The current reference for these commands is draft SBC\-4 (T10/BSR INCITS
506) revision 15 dated 9 November 2017. All six SCSI commands are
described in that document.
.SH 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.
.TP
\fB\-6\fR, \fB\-\-16\fR
send the 16 byte cdb variant of the selected SCSI command. If no command
is selected then the (normal) SCSI WRITE(16) command is sent. If neither
this option nor the \fI\-\-32\fR option is given then this option is
assumed.
.TP
\fB\-3\fR, \fB\-\-32\fR
send the 32 byte cdb variant of the selected SCSI command. If no command
is selected then the (normal) SCSI WRITE(32) command is sent. If neither
this option nor the \fI\-\-16\fR option is given then then the
\fI\-\-16\fR option is assumed. If both this option and the \fI\-\-16\fR
option are given then this option takes precedence. Note that apart
from ORWRITE(32) all other 32 byte cdb variants require a \fIDEVICE\fR
formatted with type 1, 2 or 3 protection information.
.TP
\fB\-a\fR, \fB\-\-app\-tag\fR=\fIAT\fR
where \fIAT\fR is the expected logical block application tag field found in
most of the 32 byte cdb variants (the exception is ORWRITE(32)). \fIAT\fR is
a 16 bit field which means the maximum value is 0xffff. The default value
is 0xffff .
.TP
\fB\-A\fR, \fB\-\-atomic\fR=\fIAB\fR
selects the WRITE ATOMIC command and \fIAB\fR is placed in the Atomic
Boundary field of its cdb. It is a 16 bit field so the maximum value
is 0xffff. If unsure what value to set, try 0 which will attempt to
write the whole data-out buffer in a single atomic operation.
.TP
\fB\-B\fR, \fB\-\-bmop\fR=\fIOP,PGP\fR
where \fIOP\fR and \fIPGP\fR are the values to be placed in ORWRITE(32)'s
BMOP and 'Previous Generation Processing' fields respectively. BMOP is
a 3 bit field (ranges from 0 to 7) and PGP is a 4 bit field (ranges from
0 to 15). Both fields default to 0.
.TP
\fB\-b\fR, \fB\-\-bs\fR=\fILBS\fR
where \fILBS\fR is the logical block size which is usually the same as
the logical block size of the \fIDEVICE\fR. The exception is outlined in
the DESCRIPTION section above. The default value is zero. If this option
is not given or is given with a \fILBS\fR of zero then the SCSI READ
CAPACITY(16) command is sent to \fIDEVICE\fR. If that fails then the READ
CAPACITY(10) command is sent.
.TP
\fB\-c\fR, \fB\-\-combined\fR=\fIDOF\fR
This option only applies to WRITE SCATTERED and assumes the whole data-out
buffer (including the scatter list) can be read from \fIIF\fR given by
the \fI\-\-in=IF\fR option. If the \fI\-\-lba=LBA[,LBA...]\fR,
\fI\-\-num=NUM[,NUM...]\fR or \fI\-\-scat\-file=SF\fR options are given
then they are ignored (or an error occurs if the \fI\-\-strict\fR option
is present). The \fIDOF\fR argument should be the value suitable for
the 'Logical Block Data Offset' field in the WRITE SCATTERED cdb. This is
the offset in the data-out buffer where the data to write commences. The
unit of that field is the actual block size which is the logical block
size plus 8, if protection information (PI) is being sent. When \fIWPR\fR
(from \fI\-\-wrprotect=WPR\fR) is greater than zero then PI is expected.
SBC\-4 revision 15 does not state it but it would appear that a \fIDOF\fR
value of 0 is invalid.
.TP
\fB\-D\fR, \fB\-\-dld\fR=\fIDLD\fR
where \fIDLD\fR is the duration limits descriptor spread across 3 bits in
the SCSI WRITE(16) cdb. \fIDLD\fR is between 0 to 7 inclusive with a default
of zero. The DLD0 field in WRITE(16) is set if (0x1 & \fIDLD\fR) is non\-zero.
The DLD1 field in WRITE(16) is (0x2 & \fIDLD\fR) is non\-zero. The DLD2 field
in WRITE(16) is (0x4 & \fIDLD\fR) is non\-zero.
.TP
\fB\-d\fR, \fB\-\-dpo\fR
if this option is given then the DPO (disable page out) bit field in the
cdb is set. The default is to clear this bit field.
.TP
\fB\-f\fR, \fB\-\-fua\fR
if this option is given then the FUA (force unit access) bit field in the
cdb is set. The default is to clear this bit field.
.TP
\fB\-x\fR, \fB\-\-dry\-run\fR
this option exits (with a status of 0) just before it would otherwise send
the selected SCSI write command. It may still send a SCSI READ CAPACITY
command (16 byte variant and perhaps 10 byte variant as well) and read
the data in and process it if the \fI\-\-in=IF\fR and/or the
\fI\-\-scat\-file=SF\fR options are given. All command line processing
and sanity checks (e.g. if the \fI\-\-strict\fR option is given) will be
performed and if there is an error then there will be a non zero exit
status value.
xxxxxxxxxxxxxxxxxxxxxxxxxxx
.TP
\fB\-g\fR, \fB\-\-grpnum\fR=\fIGN\fR
sets the 'Group number' field to \fIGN\fR. Defaults to a value of zero.
\fIGN\fR should be a value between 0 and 63.
.TP
\fB\-h\fR, \fB\-\-help\fR
output the usage message then exit.
.TP
\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
read data (binary) from a file named \fIIF\fR in a single OS system
call (read(2)). That data is placed in a continuous buffer and then used as
the data out buffer for the SCSI WRITE ATOMIC(16 or 32) or the normal SCSI
WRITE(16 or 32) command. The data read from \fIIF\fR starts from byte offset
\fIOFF\fR which defaults to zero and that is the start of \fIIF\fR. The
number of bytes read from \fIIF\fR is basically the product of \fINUM\fR and
\fIBS\fR (i.e. the number_of_blocks multiplied by block_size). This option
is mandatory. In Unix based OSes, any number of zeros can produced by
using the /dev/zero device file.
.TP
\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
where \fILBA\fR is the logical block address (lba) of the first block written
by the SCSI WRITE ATOMIC(16 or 32) or SCSI WRITE(16 or 32) command. Defaults
to lba 0 which is a dangerous block to overwrite on a disk that is in use.
\fILBA\fR is assumed to be in decimal unless prefixed with '0x' or has a
trailing 'h'.
.TP
\fB\-N\fR, \fB\-\-non\-atomic\fR
when this option is given either a SCSI WRITE(16) or SCSI WRITE(32) command
is sent. The default (i.e. in the absence of this option) is to send
either SCSI WRITE ATOMIC(16) or SCSI WRITE ATOMIC(32) command.
.TP
\fB\-n\fR, \fB\-\-num\fR=\fINUM\fR
where \fINUM\fR is the number of blocks, to read from the file named \fIIF\fR.
It is also the number of blocks written using a SCSI WRITE ATOMIC(16 or 32)
or a SCSI WRITE(16 or 32). The default is 0 which is the degenerate case
that will not modify the \fIDEVICE\fR but is still valid.
.TP
\fB\-o\fR, \fB\-\-offset\fR=\fIOFF\fR
where \fIOFF\fR is the byte offset within the file named \fIIF\fR to start
reading from. The default value is zero which is the beginning \fIIF\fR.
.TP
\fB\-r\fR, \fB\-\-ref\-tag\fR=\fIRT\fR
where \fIRT\fR is the expected logical block reference tag field in the
WRITE ATOMIC(32) and WRITE(32) cdbs. It is 32 bit field which means the
maximum value is 0xffffffff. The default value is zero.
.TP
\fB\-s\fR, \fB\-\-strict\fR
when this option is present, if the read of the file named \fIIF\fR yields
less bytes than requested then this utility will exit at this point
with an exit status of SG_LIB_FILE_ERROR. The default is to fill the
remaining part of the buffer with zeros and attempt to write the
full buffer to the \fIDEVICE\fR.
.TP
\fB\-T\fR, \fB\-\-tag\-mask\fR=\fITM\fR
where \fITM\fR is the logical block application tag mask field in the
WRITE ATOMIC(32) and WRITE(32) cdbs. It is 16 bit field which means the
maximum value is 0xffff. The default value is zero.
.TP
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
where \fITO\fR is the command timeout value in seconds. The default value is
120 seconds. If \fINUM\fR is large a WRITE ATOMIC command may require
considerably more time than 120 seconds to complete.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the degree of verbosity (debug messages). These messages are usually
written to stderr.
.TP
\fB\-V\fR, \fB\-\-version\fR
output version string then exit.
.TP
\fB\-w\fR, \fB\-\-wrprotect\fR=\fIWPR\fR
sets the "Write protect" field in the WRITE SAME cdb to \fIWPR\fR. The
default value is zero. \fIWPR\fR should be a value between 0 and 7.
When \fIWPR\fR is 1 or greater, and the disk's protection type is 1 or
greater, then 8 extra bytes of protection information are expected or
generated (to place in the command's data out buffer).
.SH NOTES
Various numeric arguments (e.g. \fILBA\fR) may include multiplicative
suffixes or be given in hexadecimal. See the "NUMERIC ARGUMENTS" section
in the sg3_utils(8) man page.
.PP
In Linux, prior to lk 3.17, the sg driver did not support cdb sizes greater
than 16 bytes. Hence a device node like /dev/sg1 which is associated with
the sg driver would fail with this utility if the \fI\-\-32\fR option was
given (or implied by other options). The bsg driver with device nodes like
/dev/bsg/6:0:0:1 does support cdb sizes greater than 16 bytes since its
introduction in lk 2.6.28 .
.SH EXIT STATUS
The exit status of sg_write_atomic is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH EXAMPLES
One simple usage is to write 4 blocks of zeros from (and including) a given
LBA:
.PP
  sg_write_atomic \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4 /dev/sdc
.PP
Since \fI\-\-bs=BS\fR has not been given, then this utility will call the
READ CAPACITY(16) command on /dev/sdc to determine the number of bytes in a
logical block. If the READ CAPACITY(16) command fails then the READ
CAPACITY(10) command is tried. Let us assume one of them works and that
the number of bytes in each logical block is 512 bytes. So 4 blocks of
zeros (each block containing 512 bytes) will be written from (and including)
LBA 0x1234 . Now to bypass the need for the READ CAPACITY command(s) the
\fI\-\-bs=BS\fR option can be used:
.PP
  sg_write_atomic \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4
/dev/sdc
.PP
Both of the examples above issue a SCSI WRITE ATOMIC(16) command. To send the
32 byte variant add \-\-32 as in:
.PP
  sg_write_atomic \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4
/dev/sdc
.PP
To drop the WRITE ATOMIC(32) and replace it with a normal WRITE(32) add the
\-\-non\-atomic option:
.PP
  sg_write_atomic \-\-non\-atomic \-\-32 \-\-bs=512 \-\-in=/dev/zero
\-\-lba=0x1234 \-\-num=4 /dev/sdc
.PP
.SH AUTHORS
Written by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2017 Douglas Gilbert
.br
This software is distributed under a FreeBSD license. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_readcap,sg_vpd,sg_write_same(sg3_utils)