| .TH SG_WRITE_LONG "8" "January 2007" "sg3_utils\-1.23" SG3_UTILS |
| .SH NAME |
| sg_write_long \- send the 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 the (finite number) of 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 rebooted. |
| .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 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 |
| traling '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 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). The default action is to |
| use the provided data (\fI\-\-xfer_len=BTL\fR in length) and write it to |
| \fIDEVICE\fR. This bit is 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 |
| The \fILBA\fR and \fIBTL\fR (transfer length) 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. |
| .PP |
| To read from a defective sector (that, for example, has been filled with |
| 0xff bytes by this utility) use: |
| .PP |
| sg_dd if=\fIDEVICE\fR skip=\fILBA\fR of=/dev/null bs=512 count=1 |
| .PP |
| To overwrite to a defective sector use: |
| .PP |
| sg_dd of=\fIDEVICE\fR seek=\fILBA\fR 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 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 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\-2007 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) |