doc/sg_read_long.8 - platform/external/sg3_utils - Git at Google

 .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
	.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