601 lines
32 KiB
Groff
601 lines
32 KiB
Groff
.TH SG_WRITE_X "8" "October 2021" "sg3_utils\-1.47" 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=BS\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\-\-quiet\fR] [\fI\-\-ref\-tag=RT\fR] [\fI\-\-same=NDOB\fR]
|
|
[\fI\-\-scat\-file=SF\fR] [\fI\-\-scat\-raw\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
|
|
Synopsis per supported command:
|
|
.PP
|
|
.B sg_write_x
|
|
\fI\-\-normal\fR \fI\-\-in=IF\fR [\fI\-\-16\fR] [\fI\-\-32\fR]
|
|
[\fI\-\-app\-tag=AT\fR] [\fI\-\-bs=BS\fR] [\fI\-\-dld=DLD\fR] [\fI\-\-dpo\fR]
|
|
[\fI\-\-fua\fR] [\fI\-\-grpnum=GN\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\-\-in=IF\fR [\fI\-\-16\fR] [\fI\-\-32\fR]
|
|
[\fI\-\-bmop=OP,PGP\fR] [\fI\-\-bs=BS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR]
|
|
[\fI\-\-generation=EOG,NOG\fR] [\fI\-\-grpnum=GN\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\-\-in=IF\fR [\fI\-\-16\fR] [\fI\-\-32\fR]
|
|
[\fI\-\-app-tag=AT\fR] [\fI\-\-bs=BS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR]
|
|
[\fI\-\-grpnum=GN\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=WPR\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=BS\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=WPR\fR] \fIDEVICE\fR
|
|
.PP
|
|
.B sg_write_x
|
|
\fI\-\-scattered=RD\fR \fI\-\-in=IF\fR [\fI\-\-16\fR] [\fI\-\-32\fR]
|
|
[\fI\-\-app-tag=AT\fR] [\fI\-\-bs=BS\fR] [\fI\-\-dld=DLD\fR] [\fI\-\-dpo\fR]
|
|
[\fI\-\-fua\fR] [\fI\-\-grpnum=GN\fR] [\fI\-\-lba=LBA[,LBA...]\fR]
|
|
[\fI\-\-num=NUM[,NUM...]\fR] [\fI\-\-offset=OFF[,DLEN]\fR]
|
|
[\fI\-\-ref\-tag=RT\fR] [\fI\-\-scat\-file=SF\fR] [\fI\-\-scat\-raw\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\-\-in=IF\fR [\fI\-\-16\fR] [\fI\-\-32\fR]
|
|
[\fI\-\-app-tag=AT\fR] [\fI\-\-bs=BS\fR] [\fI\-\-dpo\fR] [\fI\-\-fua\fR]
|
|
[\fI\-\-grpnum=GN\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 (or a multiple
|
|
of 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 followed by any required options. 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=BS\fR option, as long as \fIBS\fR is greater than zero. It
|
|
is typically a power of two, 512 or greater. If the \fI\-\-bs=BS\fR option
|
|
is not given or \fIBS\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 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 bytes of zero 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 a 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 (Logical Block Address) 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 (note: that is not
|
|
the default values for RT, AT and TM). 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 a 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 reference for these commands is SBC\-4 (T10/BSR INCITS 506\-2021)
|
|
and draft SBC\-5 INCITS 571 revision 1 dated 21 May 2021. All six SCSI
|
|
commands are described in those documents. WRITE ATOMIC was added in
|
|
SBC\-4 revision 3; WRITE STREAM was added in SBC\-4 revision 7; WRITE
|
|
SCATTERED was added in SBC\-4 revision 11 while the others are in the
|
|
previous SBC\-3 standard.
|
|
.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=\fIBS\fR
|
|
where \fIBS\fR is the logical block size or the actual block size which
|
|
will be slightly bigger. The default value is zero. If this option
|
|
is not given or is given with a \fIBS\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. The logical and actual block size will be
|
|
derived from the response of the READ CAPACITY command.
|
|
.br
|
|
This section assumes \fIBS\fR is greater than zero. If \fIBS\fR is less than
|
|
512 (bytes) or not a multiple of 8, a warning is issued and the utility
|
|
continues unless the \fI\-\-strict\fR option is also given. If \fIBS\fR
|
|
is a power of two (e.g. 512) then the logical and actual block size is
|
|
set to \fIBS\fR (e.g. 512). If \fIBS\fR is not a power of two (e.g. 520)
|
|
then the logical block size is set to the closest power of two less than
|
|
\fIBS\fR (e.g. 512) and the actual block size is set to \fIBS\fR (e.g.
|
|
520).
|
|
.br
|
|
If the logical and actual block size are different then a later check
|
|
will reduce the actual block size back to the logical block size unless
|
|
\fI\-\-wrprotect=WPR\fR is greater than zero.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-combined\fR=\fIDOF\fR
|
|
This option only applies to WRITE SCATTERED and assumes the whole data\-out
|
|
buffer can be read from \fIIF\fR given by the \fI\-\-in=IF\fR option. The
|
|
whole data\-out buffer is the parameter list header, followed by zero or more
|
|
LBA range descriptors, optionally followed by some pad bytes and then the
|
|
data to be written to the media. If the \fI\-\-lba=LBA[,LBA...]\fR,
|
|
\fI\-\-num=NUM[,NUM...]\fR or \fI\-\-scat\-file=SF\fR options are also given
|
|
then an error is generated. 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
|
|
to the media commences. The unit of that field is the actual block size
|
|
which is the logical block size plus a multiple of 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. It is
|
|
suggested that this option be used with the \fI\-\-strict\fR option while
|
|
experimenting as random or incorrect data fed in via the \fI\-\-in=IF\fR
|
|
option could write a lot of "interesting" data all over the \fIDEVICE\fR.
|
|
If \fIDOF\fR is given as 0 the utility will scan the data in \fIIF\fR until
|
|
\fIRD\fR LBA range descriptors are found; or if \fIRD\fR is also 0 until a
|
|
degenerate LBA range descriptor is found.
|
|
.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) and the WRITE SCATTERED(16) cdbs. \fIDLD\fR is between 0
|
|
to 7 inclusive with a default of zero. The DLD0 field in WRITE(16) and WRITE
|
|
SCATTERED(16) is set if (0x1 & \fIDLD\fR) is non\-zero. The DLD1 field in
|
|
both cdbs is set if (0x2 & \fIDLD\fR) is non\-zero. The DLD2 field in both
|
|
cdbs is set if (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. Applies to all
|
|
commands supported by thus utility except WRITE SAME.
|
|
.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) so the
|
|
\fIDEVICE\fR is still required. It reads the data in and processes 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.
|
|
.br
|
|
If this option is given twice (e.g. \-xx) then instead of performing the
|
|
selected write SCSI command, the data\-out buffer is written to a file
|
|
called sg_write_x.bin . If it doesn't exist then that file is created in
|
|
the current directory and is truncated if it previously did exist with
|
|
longer contents. The data\-out buffer is written in binary with some
|
|
information about it written to stdout. For writes other than scattered
|
|
the filename and its length in bytes is output to stdout. For write
|
|
scattered additionally its number of LBA range descriptors and its
|
|
logical block data offset written to stdout.
|
|
.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. Applies to all
|
|
commands supported by thus utility except WRITE SAME.
|
|
.TP
|
|
\fB\-G\fR, \fB\-\-generation\fR=\fIEOG,NOG\fR
|
|
the arguments for this option are used by the ORWITE(32) command only.
|
|
\fIEOG\fR is placed in the "Expected ORWgeneration" field while \fINOG\fR
|
|
is placed in the "New ORWgeneration" field. Both are 32 bits long and
|
|
default to zero.
|
|
.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. Use multiple times for more help.
|
|
Currently '\-h' to '\-hhhh' provide different output.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-in\fR=\fIIF\fR
|
|
read data (in binary) from a file named \fIIF\fR in a single OS system
|
|
call (in Unix: read(2)). That data is placed in a continuous buffer and then
|
|
used as the data\-out buffer for all SCSI write commands apart from WRITE
|
|
SCATTERED(16 or 32) which may include other data in the data\-out buffer.
|
|
For WRITE SCATTERED (16 or 32) the data\-out buffer is made up of 3 or 4
|
|
components in this order: a parameter list header (32 zero bytes); zero or
|
|
more LBA range descriptors, optionally some pad bytes (zeros) and then data
|
|
to write to the media. For WRITE SCATTERED \fIIF\fR only provides the data
|
|
to write to the media unless \fI\-\-combined=DOF\fR is given. When the
|
|
\fI\-\-combined=DOF\fR option is given \fIIF\fR contains all components of
|
|
the WRITE SCATTERED data\-out buffer in binary. The data read from \fIIF\fR
|
|
starts from byte offset \fIOFF\fR which defaults to zero and no more than
|
|
\fIDLEN\fR bytes are read from that point (i.e. from the file byte offset
|
|
\fIOFF\fR). If \fIDLEN\fR is zero or not given the rest of the file \fIIF\fR
|
|
is read. This option is mandatory apart from when \-\-same=1 is given (that
|
|
sets the NDOB bit which stands for "No Data Out Buffer"). In Unix based
|
|
OSes, any number of zeros can be produced by using the /dev/zero device file.
|
|
.br
|
|
\fIIF\fR may be "\-" which is taken as stdin. In this case the
|
|
\fI\-\-offset=OFF,DLEN\fR can be given with \fIOFF\fR set to 0 and
|
|
\fILEN\fR set to a non\-zero value, preferably a multiple of the actual block
|
|
size. The utility can also deduce how long the \fIIF\fR should be from
|
|
\fINUM\fR (or the sum of them in the case of a scatter list).
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-lba\fR=\fILBA[,LBA...]\fR
|
|
where the argument is a single Logical Block Address (LBA) or a comma
|
|
separated list of \fILBA\fRs each of which is the address of the first block
|
|
written by the selected write command. Only the WRITE SCATTERED command
|
|
can usefully take more than one \fILBA\fR. Whatever number of \fILBA\fRs is
|
|
given, there needs to be an equal number of \fINUM\fRs given to the
|
|
\fI\-\-num=NUM[,NUM...]\fR option. The first given \fILBA\fR joins with the
|
|
first given \fINUM\fR to form the first LBA range descriptor (which T10
|
|
number from zero in SBC\-4). The second \fILBA\fR joins with the second
|
|
\fILBA\fR to form the second LBA range descriptor, etc. A more convenient
|
|
way to define a large number of LBA range descriptors is with the
|
|
\fI\-\-scat\-file=SF\fR option. Defaults to logical block 0 (which could be
|
|
dangerous) while \fINUM\fR defaults to 0 which makes the combination harmless.
|
|
\fILBA\fR is assumed to be in decimal unless prefixed with '0x' or has a
|
|
trailing 'h'.
|
|
.TP
|
|
\fB\-N\fR, \fB\-\-normal\fR
|
|
the choice of a "normal" WRITE (16 or 32) command can be made explicitly
|
|
with this option. In the absence of selecting any other command (e.g.
|
|
\fI\-\-atomic=AB\fR ), the choice of a "normal" WRITE is the default.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-num\fR=\fINUM[,NUM...]\fR
|
|
where the argument is a single NUMber of blocks (NUM) or a comma separated
|
|
list of \fINUM\fRs that pair with the corresponding entries in the
|
|
\fI\-\-lba=LBA[,LBA...]\fR option. If a \fINUM\fR is given and is not
|
|
provided by another method (e.g. by using the \fI\-\-scat\-file=SF\fR option)
|
|
then it defaults to the number of blocks derived from the size of the file
|
|
named by \fIIF\fR (starting at byte offset \fIOFF\fR to the end or the file
|
|
or \fIDLEN\fR). Apart from the \fI\-\-combined=DOF\fR option, an LBA must
|
|
be explicitly given (either with \fII\-\-lba=LBA\fR or via
|
|
\fI\-\-scat\-file=SF\fR), if not \fINUM\fR defaults to 0 as a safety measure.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-offset\fR=\fIOFF[,DLEN]\fR
|
|
where \fIOFF\fR is the byte offset within the file named \fIIF\fR to start
|
|
reading from. The default value of \fIOFF\fR is zero which is the beginning
|
|
of file named \fIIF\fR. \fIDLEN\fR is the maximum number of bytes to read,
|
|
starting at byte offset \fIOFF\fR, from the file named \fIIF\fR. Less bytes
|
|
will be read if an end of file occurs before \fIDLEN\fR is exhausted. If
|
|
\fIDLEN\fR is zero or not given then reading from byte offset \fIOFF\fR to
|
|
the end of the file named \fIIF\fR is assumed.
|
|
.TP
|
|
\fB\-O\fR, \fB\-\-or\fR
|
|
selects the ORWRITE command. ORWRITE(16) has similar fields to WRITE(16)
|
|
apart from the WRPROTECT field being named ORPROTECT with slightly different
|
|
semantics and the absence of the 3 DLD bit fields. ORWRITE(32) has four
|
|
extra fields that are set with the \fI\-\-bmop=OP,PGP\fR and
|
|
\fI\-\-generation=EOG,NOG\fR options. ORWRITE(32) is the only 32 byte cdb
|
|
command in this utility that does not require a \fIDEVICE\fR formatted with
|
|
type 1, 2 or 3 PI (although it will still work if it is formatted with PI).
|
|
.TP
|
|
\fB\-Q\fR, \fB\-\-quiet\fR
|
|
suppress some informational messages such as the ones associated with
|
|
detected errors when this utility is about to exit. The exit status value
|
|
is still returned to the operating system when this utility exits.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-ref\-tag\fR=\fIRT\fR
|
|
where \fIRT\fR is the "expected initial logical block reference tag" field
|
|
found in the 32 byte cdb variants of WRITE, WRITE ATOMIC, WRITE SAME and
|
|
WRITE STREAM. The field is also found in the WRITE SCATTERED(32) LBA range
|
|
descriptors. It is a 32 bit field which means the maximum value is
|
|
0xffffffff. The default value is 0xffffffff.
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-same\fR=\fINDOB\fR
|
|
selects the WRITE SAME command with the NDOB field set to \fINDOB\fR which
|
|
stands for No Data\-Out Buffer. \fINDOB\fR can take values 0 or 1 (i.e. it
|
|
is a single bit field). When \-\-same=1 all options associated with the
|
|
data\-out buffer are ignored.
|
|
.TP
|
|
\fB\-q\fR, \fB\-\-scat\-file\fR=\fISF\fR
|
|
where \fISF\fR is the name of an auxiliary file containing the scatter list
|
|
for the WRITE SCATTERED command. If the \fI\-\-scat\-raw\fR option is also
|
|
given then \fISF\fR is assumed to contain both the parameter list header (32
|
|
bytes of zeros) followed by zero or more LBA range descriptors which are
|
|
also 32 bytes long each. These components are as defined by SBC\-4 (i.e.
|
|
in binary with integers in big endian format). If the \fI\-\-scat\-raw\fR
|
|
option is not given then a file of ACSII hexadecimal is expected as described
|
|
in the SCATTERED FILE ASCII FORMAT section below.
|
|
.br
|
|
If this option is given with the \fI\-\-combined=DOF\fR option then this
|
|
utility will exit with a syntax error. \fISF\fR must not be "\-", a way
|
|
of stopping the user trying to redirect stdin.
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-scat\-raw\fR
|
|
this option only effects the way that the file named \fISF\fR from the
|
|
\fI\-\-scat\-file=SF\fR option for WRITE SCATTERED is interpreted. By
|
|
default (i.e. without this option), \fISF\fR is parsed as ASCII hexadecimal
|
|
with blank lines and line contents from and including '#' to the end of
|
|
line ignored. Hence it can contain comments and other indications. When
|
|
this option is given, the file named \fISF\fR is interpreted as binary.
|
|
As binary it is assumed to contain 32 bytes of zeros (the WRITE SCATTERED
|
|
parameter list header) followed by zero or more LBA range descriptors (which
|
|
are 32 bytes each). If the \fI\-\-strict\fR option is given the reserved
|
|
field in those two items are checked with any non zero bytes causing an
|
|
error.
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-scattered\fR=\fIRD\fR
|
|
selects the WRITE SCATTERED command with \fIRD\fR being the number of LBA
|
|
range descriptors that will be placed in the data\-out buffer. If \fIRD\fR
|
|
is zero then the logic will try and determine the number of range descriptors
|
|
by other means (e.g. by parsing the file named by \fISF\fR, if there is one).
|
|
The LBA range descriptors differ between the 16 and 32 byte cdb variants of
|
|
WRITE SCATTERED. In the 16 byte cdb variant the 32 byte LBA range descriptor
|
|
is made up of an 8 byte LBA, followed by a 4 byte number_of_blocks followed
|
|
by 20 bytes of zeros. In the 32 byte variant the LBA and number_of_blocks
|
|
are followed by a RT (4 bytes), an AT (2 bytes) and a TM (2 bytes) then
|
|
12 bytes of zeros.
|
|
.br
|
|
This paragraph applies when \fIRD\fR is greater than zero.
|
|
If \fIRD\fR is less than the number of LBA range descriptors built from
|
|
command line options, from the \fI\-\-scat\-file=SF\fR option or
|
|
decoded from \fIIF\fR (when the \fI\-\-combined=DOF\fR option is given)
|
|
then \fIRD\fR takes precedence; so \fIRD\fR is placed in the "Number of
|
|
LBA Range Descriptors" field in the cdb. If \fIRD\fR is greater than
|
|
the number of LBA range descriptors found from the provided data and
|
|
options, then an error is generated.
|
|
.TP
|
|
\fB\-T\fR, \fB\-\-stream\fR=\fIID\fR
|
|
selects the WRITE STREAM command with the STR_ID field set to \fIID\fR.
|
|
\fIID\fR can take values from 0 to 0xffff (i.e. it is a 16 bit field).
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-strict\fR
|
|
when this option is present, more things (e.g. that reserved fields contain
|
|
zeros) and any irregularities will terminate the utility with a message to
|
|
stderr and an indicative exit status. While experimenting with these commands,
|
|
especially WRITE SCATTERED, it is recommended to use this option.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-tag\-mask\fR=\fITM\fR
|
|
where \fITM\fR is the "logical block application tag mask" field found in the
|
|
32 byte cdb variants of WRITE, WRITE ATOMIC, WRITE SAME and WRITE STREAM. The
|
|
field is also found in the WRITE SCATTERED(32) LBA range descriptors. It is a
|
|
16 bit field which means the maximum value is 0xffff. The default value is
|
|
0xffff.
|
|
.TP
|
|
\fB\-I\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 on slow media then these WRITE commands
|
|
may require considerably more time than 120 seconds to complete.
|
|
.TP
|
|
\fB\-u\fR, \fB\-\-unmap\fR=\fIU_A\fR
|
|
where \fIU_A\fR is OR\-ed bit values used to set the UNMAP and ANCHOR bit
|
|
fields in the WRITE SAME (16 or 32) cdb. If \fIU_A\fR is 1 then the UNMAP
|
|
bit field is set; if \fIU_A\fR is 2 then the ANCHOR bit field is set; if
|
|
\fIU_A\fR is 3 then both the UNMAP and ANCHOR bit fields are set. The
|
|
default value for both bit fields is clear (0); setting \fIU_A\fR to 0 will
|
|
also clear both bit fields.
|
|
.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 WRPROTECT field (3 bits) in all sg_write_x commands apart from
|
|
ORWRITE which has a 3 bit ORPROTECT field (and the synopsis shows \fIOPR\fR
|
|
to highlight the difference). In all cases \fIWPR\fR is placed
|
|
in that 3 bit field. The default value is zero which does not send any PI
|
|
in the data\-out buffer. \fIWPR\fR should be a value between 0 and 7.
|
|
.SH SCATTERED FILE ASCII FORMAT
|
|
All commands in this utility can take a \fI\-\-scat\-file=SF\fR and that
|
|
option can be seen as a replacement for the \fI\-\-lba=LBA[,LBA...]\fR and
|
|
\fI\-\-num=NUM[,NUM...]\fR options. if both the \fI\-\-scat\-file=SF\fR and
|
|
\fI\-\-scat\-raw\fR options are given then the file named \fISF\fR is
|
|
expected to be binary and contain the parameter list header (32 bytes of
|
|
zeros for both the 16 and 32 byte variants) followed by zero or more LBA
|
|
range descriptors, each of 32 bytes each. This section describes what is
|
|
expected in \fISF\fR when the \fI\-\-scat\-raw\fR option is not given.
|
|
.PP
|
|
The ASCII hexadecimal "scatter file" (named by \fISF\fR) can contain
|
|
comments, empty lines and numbers. If multiple numbers appear on one line
|
|
they can be separated by spaces, tabs or a single comma. Numbers are parsed
|
|
as decimal unless prefixed by "0x" (or "0X") or have a suffix of "h". Ox is
|
|
the prefix of hexadecimal number is the C language while T10 uses the "h"
|
|
suffix for the same purpose. Anything from and including a "#" character
|
|
to the end\-of\-line is ignored, so comments can be placed there.
|
|
.PP
|
|
For the WRITE SCATTERED (16) command, its LBA range descriptors contain two
|
|
items per descriptor: an 8 byte LBA followed by a 4 byte number_of_blocks.
|
|
The remaining 20 bytes of the descriptor are zeros. The format accepted
|
|
is relatively loose with each decoded value being placed in an LBA and
|
|
then a number_of_blocks until the end\-of\-file is reached. The pattern
|
|
starts with a LBA and if it doesn't finish with a number_of_blocks (i.e.
|
|
an odd number of values are parsed) an error occurs. So the number of
|
|
LBA range descriptors generated will be half the number of values parsed
|
|
in \fISF\fR.
|
|
.PP
|
|
For the WRITE SCATTERED (32) command, its LBA range descriptors contain five
|
|
items per descriptor: an 8 byte LBA followed by a 4 byte number_of_blocks,
|
|
then a 4 byte RT, a 2 byte AT, and a 2 byte TM. The last three items are
|
|
associated with protection information (PI). The accepted format in the
|
|
\fISF\fR file is more constrained than the 16 byte cdb variant. The items
|
|
for each LBA range descriptor must be found on one line with adjacent items
|
|
being comma separated. The first two items (LBA and number_of_blocks) must be
|
|
given, and if no more items are on the line then RT, AT and TM are given
|
|
their default values (all "ff" bytes). Spaces and tabs may appear between
|
|
items but commas are the separators. Two commas with no value between them
|
|
will cause the "missing" item to receive its default value.
|
|
.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_x 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 according to the rules of WRITE ATOMIC with an atomic boundary of 0.
|
|
Since no cdb size option is given, the 16 byte cdb will be assumed (i.e.
|
|
WRITE ATOMIC(16)):
|
|
.PP
|
|
sg_write_x \-\-atomic=0 \-\-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_x \-\-atomic=0 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234 \-\-num=4
|
|
/dev/sdc
|
|
.PP
|
|
Since \-\-bs= is given and its value (512) is a power of 2, then the actual
|
|
block size is also 512. If instead 520 was given then the logical block size
|
|
would be 512 (the highest power of 2 less than 520) and the actual block size
|
|
would be 520 bytes. To send the 32 byte variant add \-\-32 as in:
|
|
.PP
|
|
sg_write_x \-\-atomic=0 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234
|
|
\-\-num=4 /dev/sdc
|
|
.PP
|
|
For examples using 'sg_write_x \-\-same=NDOB' see the manpage for
|
|
sg_write_same(8). The syntax is a little different but the semantics are the
|
|
same.
|
|
.PP
|
|
To send a WRITE STREAM(32) with a STR_ID of 1 use the following:
|
|
.PP
|
|
sg_write_x \-\-stream=1 \-\-32 \-\-bs=512 \-\-in=/dev/zero \-\-lba=0x1234
|
|
\-\-num=4 /dev/sdc
|
|
.PP
|
|
Next is a WRITE SCATTERED(16) command with the scatter list, split between
|
|
the \-\-lba= and \-\-num= options, on the command line:
|
|
.PP
|
|
sg_write_x \-\-scattered=2 \-\-lba=2,0x33 \-\-num=4,1 -i /dev/zero /dev/sg1
|
|
.PP
|
|
Example of a WRITE SCATTERED(16) command with a degenerate LBA range
|
|
descriptor (first element to \-\-lba= and \-\-num=):
|
|
.PP
|
|
sg_write_x \-\-scattered=2 \-\-lba=0,0x33 \-\-num=0,1 -i /dev/zero /dev/sg1
|
|
.PP
|
|
Example of a WRITE SCATTERED(16) command with the scatter list in
|
|
scat_file.txt
|
|
.PP
|
|
sg_write_x \-\-scattered=3 \-q scat_file.txt \-i /dev/zero /dev/sg1
|
|
.PP
|
|
Next a WRITE SCATTERED(16) command with its scatter list and data in a
|
|
single file. Note that the argument to \-\-scattered= is 0 so the number of
|
|
LBA range descriptors is calculated by analyzing the first two blocks of
|
|
scat_data.bin (because the argument to \-\-combined= is 2) :
|
|
.PP
|
|
sg_write_x \-\-scattered=0 \-\-combined=2 \-i scat_data.bin /dev/sg1
|
|
.PP
|
|
When the \-xx option is used, a WRITE SCATTERED command is not executed
|
|
but instead the contents of the data\-out buffer are written to a file
|
|
called sg_write_x.bin . In the case of WRITE SCATTERED that binary file
|
|
is suitable for supplying to a later invocation to do the actual write
|
|
to media. For example:
|
|
.PP
|
|
sg_write_x \-\-scattered=3 \-q scat_file.txt \-xx \-i /dev/zero /dev/sg1
|
|
.br
|
|
Wrote 8192 bytes to sg_write_x.bin, LB data offset: 1
|
|
.br
|
|
Number of LBA range descriptors: 3
|
|
.br
|
|
sg_write_x \-\-scattered=0 \-\-combined=1 \-i sg_write_x.bin /dev/sg1
|
|
.PP
|
|
Notice when the sg_write_x.bin is written (and nothing is written to the
|
|
media), a summary of what has happened is sent to stdout. The value shown
|
|
for "LB data offset:" (1) should be given to the \-\-combined= option
|
|
when the write to media actually occurs (i.e. the second invocation shown
|
|
directly above).
|
|
.SH AUTHORS
|
|
Written by Douglas Gilbert.
|
|
.SH "REPORTING BUGS"
|
|
Report bugs to <dgilbert at interlog dot com>.
|
|
.SH COPYRIGHT
|
|
Copyright \(co 2017\-2021 Douglas Gilbert
|
|
.br
|
|
This software is distributed under a BSD\-2\-Clause 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,sg_stream_ctl(sg3_utils)
|