1 files changed, 102 insertions, 0 deletions
diff --git a/doc/sg_read_long.8 b/doc/sg_read_long.8
new file mode 100644
index 00000000..e1b1591a
--- /dev/null
+++ b/doc/sg_read_long.8
@@ -0,0 +1,102 @@
+.TH SG_READ_LONG "8" "November 2015" "sg3_utils\-1.42" SG3_UTILS
+.SH NAME
+sg_read_long \- send a SCSI READ LONG command
+.SH SYNOPSIS
+.B sg_read_long
+[\fI\-\-16\fR] [\fI\-\-correct\fR] [\fI\-\-help\fR] [\fI\-\-lba=LBA\fR]
+[\fI\-\-out=OF\fR] [\fI\-\-pblock\fR] [\fI\-\-readonly\fR] [\fI\-\-verbose\fR]
+[\fI\-\-version\fR] [\fI\-\-xfer_len=BTL\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Send SCSI READ LONG command to \fIDEVICE\fR. The read buffer is output in hex
+and ASCII to stdout or placed in a file. Note that the data returned includes
+the logical block data (typically 512 bytes for a disk) plus ECC
+information (whose format is proprietary) plus optionally other proprietary
+data. Note that the logical block data may be encoded or encrypted.
+.PP
+In SBC\-4 revision 7 the SCSI READ LONG (10 and 16 byte) commands were made
+obsolete. In the same revision 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.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-S\fR, \fB\-\-16\fR
+uses a SCSI READ LONG(16) command. The default action is to use a SCSI
+READ LONG(10) command. The READ LONG(10) command has a 32 bit field for
+the lba while READ LONG(16) has a 64 bit field.
+.TP
+\fB\-c\fR, \fB\-\-correct\fR
+sets the 'CORRCT' bit in the SCSI READ LONG command. When set the data is
+corrected by the ECC before being transferred back to this utility. The
+default is to leave the 'CORRCT' bit clear in which case the data is
+not corrected.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-l\fR, \fB\-\-lba\fR=\fILBA\fR
+where \fILBA\fR is the logical block address of the sector to read. Assumed
+to be in decimal unless prefixed with '0x' (or has a trailing 'h'). Defaults
+to lba 0. If the lba is larger than can fit in 32 bits then the \fI\-\-16\fR
+option should be used.
+.TP
+\fB\-o\fR, \fB\-\-out\fR=\fIOF\fR
+instead of outputting ASCII hex to stdout, send it in binary to the
+file called \fIOF\fR. If '\-' is given for \fIOF\fR then the (binary)
+output is sent to stdout. Note that all informative and error output is
+sent to stderr.
+.TP
+\fB\-p\fR, \fB\-\-pblock\fR
+sets the 'PBLOCK' bit in the SCSI READ LONG command. When set the
+physical block (plus ECC data) containing the requested logical block
+address is read. The default is to leave the 'PBLOCK' bit clear in
+which case the logical block (plus any ECC data) is read.
+.TP
+\fB\-r\fR, \fB\-\-readonly\fR
+opens the DEVICE read\-only rather than read\-write which is the
+default. The Linux sg driver needs read\-write access for the SCSI
+READ LONG command but other access methods may require read\-only
+access.
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
+increase the level of verbosity, (i.e. debug output).
+.TP
+\fB\-V\fR, \fB\-\-version\fR
+print the version string and then exit.
+.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, the appropriate \fIBTL\fR is deduced from the error response and
+printed (to stderr). The idea is that the user will retry this utility
+with the correct transfer length.
+.SH NOTES
+If a defective block is found and its contents, if any, has been
+retrieved then "sg_reassign" could be used to map out the defective
+block. Associated with such an action the number of elements in
+the "grown" defect list could be monitored (with "sg_reassign \-\-grown")
+as the disk could be nearing the end of its useful lifetime.
+.PP
+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
+As a data point, Fujitsu uses a 54 byte ECC (per block) which is capable
+of correcting up to a single burst error or 216 bits "on the
+fly". [Information obtained from MAV20xxrc product manual.]
+.SH EXIT STATUS
+The exit status of sg_read_long is 0 when it is successful. Otherwise see
+the sg3_utils(8) man page.
+.SH AUTHORS
+Written 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_reassign, sg_write_long, sg_dd