diff options
Diffstat (limited to 'doc/sg_write_long.8')
| -rw-r--r-- | doc/sg_write_long.8 | 176 |
1 files changed, 176 insertions, 0 deletions
diff --git a/doc/sg_write_long.8 b/doc/sg_write_long.8 new file mode 100644 index 00000000..2d5560d7 --- /dev/null +++ b/doc/sg_write_long.8 @@ -0,0 +1,176 @@ +.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) |