path: root/sg_write_long.8

.TH SG_WRITE_LONG "8" "June 2006" "sg3_utils-1.21" SG3_UTILS
.SH NAME
sg_write_long \- send the SCSI command write long
.SH SYNOPSIS
.B sg_write_long
[\fI--cor_dis\fR] [\fI--help\fR] [\fI--in=<name>\fR] [\fI--lba=<num>\fR]
[\fI--verbose\fR] [\fI--version\fR] [\fI--xfer_len=<num>\fR]
\fI<scsi_device>\fR
.SH DESCRIPTION
.\" Add any additional description here
.PP
Send WRITE LONG (10) command to a Linux SCSI device. The
buffer to be written to the device is filled with
.B 0xff
bytes or read from the given file. This buffer includes the sector data
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. Prior to testing, the
.B sg_dd
utility could be used to copy the original contents of the logical
block address to some safe location. After testing 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) all set
then recovered errors will cause the lba to be reassigned (and the old
location to be added to the grown defect list). This is not easily 
reversed and uses the (finite number) of spare blocks sets 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 rebooted (assuming the "saved" bits are set).
.TP
--cor_dis | -c
sets the correction disabled bit. This inhibits various other
mechanisms such as automatic block reallocation, error recovery
and various informational exception conditions being triggered.
.TP
--help | -h
output the usage message then exit.
.TP
--in=<name> | -i <name>
read data (binary) from given file <name> and use it for the WRITE LONG
SCSI command. If <name> is "-" then stdin is read. If this option is
not given then a buffer of 0xff bytes is written.
.TP
--lba=<num> | -l <num>
the logical block address of the sector to corrupt. 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'. Only 32 bit
lbas currently supported.
.TP
--verbose | -v
increase the degree of verbosity (debug messages).
.TP
--version | -V
output version string then exit.
.TP
--xfer_len=<num>|-x <num>
the transfer length in bytes (default to 520). If the given value (or the
default) does not match the "long" block size of the device, nothing is
written to the device and the appropriate xfer_len value is derived from the
error response and printed (to stderr).
.PP
The lba and xfer_len numerical arguments may be followed by the following
multiplicative suffixes:
c C *1; w W *2; b B *512; k K KiB *1,024; KB *1,000; m M MiB *1,048,576;
MB *1,000,000; g G GiB *1,073,741,824; and GB *1,000,000,000 . Also a suffix
of the form "x<n>" multiplies the leading number by <n>.
.PP
Alternatively numerical values can be given in hexadecimal preceded by
either "0x" or "0X" (or with a trailing "h" or "H"). When hex numbers are
given, multipliers cannot be used.
.SH "NOTES"
To read from a defective sector (that, for example, has been filled with
0xff bytes by this utility) use:
.PP
  sg_dd if=<scsi_device> skip=<lba> of=/dev/null bs=512 count=1
.PP
To overwrite to a defective sector use:
.PP
  sg_dd of=<scsi_device> seek=<lba> if=/dev/zero 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 well formed.
.PP
The 10 byte WRITE LONG SCSI command is implemented (not the 16
byte variant). This limits the logical block address to a 32 bit
quantity.
.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-2006 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)