doc/sg_write_long.8

.TH SG_WRITE_LONG "8" "January 2016" "sg3_utils\-1.42" SG3_UTILS
.SH NAME
sg_write_long \- send SCSI WRITE LONG command
.SH SYNOPSIS
.B sg_write_long
[\fI\-\-16\fR] [\fI\-\-cor_dis\fR] [\fI\-\-help\fR] [\fI\-\-in=IF\fR]
[\fI\-\-lba=LBA\fR] [\fI\-\-pblock\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] [\fI\-\-wr_uncor\fR] [\fI\-\-xfer_len=BTL\fR]
\fIDEVICE\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
Send the SCSI WRITE LONG (10 or 16 byte) command to \fIDEVICE\fR. The buffer
to be written to the \fIDEVICE\fR is filled with
.B 0xff
bytes or read from the \fIIF\fR file. This buffer includes the logical
data (e.g. 512 bytes) and the ECC bytes.
.PP
This utility can be used to generate a MEDIUM ERROR at a specific logical
block address. This can be useful for testing error handling. Prior to
such a test, the
.B sg_dd
utility could be used to copy the original contents of the logical
block address to some safe location. After the test the
.B sg_dd
utility could be used to write back the original contents of the
logical block address. An alternate strategy would be to read the "long"
contents of the logical block address with
.B sg_read_long
utility prior to testing and restore it with this utility after testing.
.PP
.B Take care:
If recoverable errors are being injected (e.g. only one or a few bits
changed so that the ECC is able to correct the data) then care should
be taken with the settings in the "read write error recovery" mode page.
Specifically if the ARRE (for reads) and/or AWRE (for writes) are set
then recovered errors will cause the lba to be reassigned (and the old
location to be added to the grown defect list (PLIST)). This is not easily
reversed and uses (one of the finite number of) the spare sectors set
aside for this purpose. If in doubt it is probably safest to clear the
ARRE and AWRE bits. These bits can be checked and modified with the
sdparm utility.  For example: "sdparm \-c AWRE,ARRE /dev/sda" will clear
the bits until the disk is power cycled.
.PP
In SBC\-4 revision 7 all uses of SCSI WRITE LONG (10 and 16 byte) commands
were made obsolete apart from the case in which the WR_UNCOR bit is set.
The SCSI READ LONG (10 and 16 byte) commands were made obsolete in the
same revision.
.SH OPTIONS
Arguments to long options are mandatory for short options as well.
.TP
\fB\-S\fR, \fB\-\-16\fR
send a SCSI WRITE LONG (16) command to \fIDEVICE\fR. The default action (in
the absence of this option) is to send a SCSI WRITE LONG (10) command.
.TP
\fB\-c\fR, \fB\-\-cor_dis\fR
sets the correction disabled (i.e 'COR_DIS') bit. This inhibits various
other mechanisms such as automatic block reallocation, error recovery
and various informational exception conditions being triggered.
This bit is relatively new in SBC\-3 .
.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 file named \fIIF\fR and use it for the SCSI WRITE
LONG command. If \fIIF\fR is "\-" then stdin is read. If this option is
not given then 0xff bytes are used as fill.
.TP
\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
where \fILBA\fR is the logical block address of the sector to overwrite.
Defaults to lba 0 which is a dangerous block to overwrite on a disk that is
in use. Assumed to be in decimal unless prefixed with '0x' or has a
trailing 'h'. If \fILBA\fR is larger than can fit in 32 bits then the
\fI\-\-16\fR option should be used.
.TP
\fB\-p\fR, \fB\-\-pblock\fR
sets the physical block (i.e 'PBLOCK') bit. This instructs \fIDEVICE\fR
to use the given data (unless \fI\-\-wr_uncor\fR is also given) to write
to the physical block specified by \fILBA\fR. The default action
is to write to the logical block corresponding to the given lba.
This bit is relatively new in SBC\-3 .
.TP
\fB\-v\fR, \fB\-\-verbose\fR
increase the degree of verbosity (debug messages).
.TP
\fB\-V\fR, \fB\-\-version\fR
output version string then exit.
.TP
\fB\-w\fR, \fB\-\-wr_uncor\fR
sets the "write uncorrected" (i.e 'WR_UNCOR') bit. This instructs the
\fIDEVICE\fR to flag the given lba (or the physical block that contains it
if \fI\-\-pblock\fR is also given) as having an unrecoverable error
associated with it. Note: no data is transferred to \fIDEVICE\fR,
other than the command (i.e. the cdb). In the absence of this option, the
default action is to use the provided data or 0xff
bytes (\fI\-\-xfer_len=BTL\fR in length) and write it to \fIDEVICE\fR.
This bit is relatively new in SBC\-3 .
.TP
\fB\-x\fR, \fB\-\-xfer_len\fR=\fIBTL\fR
where \fIBTL\fR is the byte transfer length (default to 520). If the
given value (or the default) does not match the "long" block size of the
device, nothing is written to \fIDEVICE\fR and the appropriate xfer_len value
may be deduced from the error response which is printed (to stderr).
.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
The 10 byte SCSI WRITE LONG command limits the logical block address
to a 32 bit quantity. For larger LBAs use the \fI\-\-16\fR option for the
SCSI WRITE LONG (16) command.
.SH EXAMPLES
This section outlines setting up a block with corrupted data, checking the
error condition, then restoring useful contents to that sector.
.PP
First, if the data in a sector is important, save it with the sg_read_long
utility:
.PP
  sg_read_long \-\-lba=0x1234 \-\-out=0x1234_1.img \-x \fIBTL\fR /dev/sda
.PP
This utility may need to be executed several time in order to determine
what the correct value for \fIBTL\fR is.
Next use this utility to "corrupt" that sector. That might be done with:
.PP
  sg_write_long \-\-lba=0x1234 \-x \fIBTL\fR /dev/sda
.PP
This will write a sector (and ECC data) of 0xff bytes. Some disks may
reject this (at least one of the author's does). Another approach is
to copy the 0x1234_1.img file (to 0x1234_2.img in this example) and
change some values with a hex editor. Then write the changed image with:
.PP
  sg_write_long \-\-lba=0x1234 \-\-in=0x1234_2.img \-x \fIBTL\fR /dev/sda
.PP
Yet another approach is to use the \fI\-\-wr_uncor\fR option, if supported:
.PP
  sg_write_long \-\-lba=0x1234 \-\-wr_uncor /dev/sda
.PP
Next we use the sg_dd utility to check that the sector is corrupted. Here is an
example:
.PP
  sg_dd if=/dev/sda blk_sgio=1 skip=0x1234 of=. bs=512 count=1 verbose=4
.PP
Notice that the "blk_sgio=1" option is given. This is to make sure that
the sector is read (and no others) and the error is fully reported.
The "blk_sgio=1" option causes the SG_IO ioctl to be used by sg_dd rather
than the block subsystem.
.PP
Finally we should restore sector 0x1234 to a non\-corrupted state. A sector
full of zeros could be written with:
.PP
  sg_dd if=/dev/zero of=/dev/sda blk_sgio=1 seek=0x1234 bs=512 count=1
.PP
This will result in a sector (block) with 512 bytes of 0x0 without a
MEDIUM ERROR since the ECC and associated data will be regenerated and
thus well formed. The 'blk_sgio=1' option is even more important in this
case as it may stop the block subsystem doing a read before write (since
the read will most likely fail).
Another approach is to write back the original contents:
.PP
  sg_write_long \-\-lba=0x1234 \-\-in=0x1234_1.img \-x \fIBTL\fR /dev/sda
.PP
.SH EXIT STATUS
The exit status of sg_write_long is 0 when it is successful. Otherwise see
the sg3_utils(8) man page.
.SH AUTHORS
Written by Saeed Bishara. Further work by Douglas Gilbert.
.SH "REPORTING BUGS"
Report bugs to <dgilbert at interlog dot com>.
.SH COPYRIGHT
Copyright \(co 2004\-2016 Douglas Gilbert
.br
This software is distributed under the GPL version 2. There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
.SH "SEE ALSO"
.B sg_read_long, sg_dd (both in sg3_utils), sdparm(sdparm)