rearrange files into include, src, lib and doc directories

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@100 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 144 insertions, 0 deletions

diff --git a/doc/sg_reassign.8 b/doc/sg_reassign.8
new file mode 100644
index 00000000..649227e3
--- /dev/null
+++ b/doc/sg_reassign.8
@@ -0,0 +1,144 @@
+.TH SG_REASSIGN "8" "January 2007" "sg3_utils\-1.23" SG3_UTILS
+.SH NAME
+sg_reassign \- sends a SCSI REASSIGN BLOCKS command
+.SH SYNOPSIS
+.B sg_reassign
+[\fI\-\-address=A,A...\fR] [\fI\-\-dummy\fR] [\fI\-\-eight=0|1\fR]
+[\fI\-\-grown\fR] [\fI\-\-help\fR] [\fI\-\-longlist=0|1\fR]
+[\fI\-\-primary\fR] [\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
+.SH DESCRIPTION
+.\" Add any additional description here
+.PP
+Send a SCSI REASSIGN BLOCKS command to \fIDEVICE\fR. Alternatively
+this utility can find the number of element in a "grown" or "primary"
+defect list with a SCSI READ DEFECT DATA (10) command. These SCSI commands
+are defined in SBC\-2 for direct access devices (e.g. a disk). Reassign
+blocks is designed to change the physical location of a logical block
+that is known or suspected to be defective to another area on the
+media. Disks are typically formatted with blocks held in reserve
+for this situation. 
+.PP
+If neither the \fI\-\-grown\fR nor \fI\-\-primary\fR option is supplied
+then one or more addresses need to be given. If the address (or all of
+the addresses) fit into 4 bytes and '\-\-eight=1' is not given then the
+parameter block passed to \fIDEVICE\fR is made up of 4 byte logical block
+addresses. If any of the addresses need more than 4 bytes to
+represent (i.e. >= 2**32) or '\-\-eight=1' is given then the parameter block
+passed to \fIDEVICE\fR is made up of 8 byte logical block addresses.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.TP
+\fB\-a\fR, \fB\-\-address\fR=\fIA,A...\fR
+where \fIA,A...\fR is a string of comma separated numbers. Each number
+is interpreted as decimal unless prefixed by '0x' or '0X' (or it has a
+trailing 'h' or 'H'). If multiple logical block addresses are given they
+must be separated by a comma. At least one address must be given.
+.TP
+\fB\-a\fR, \fB\-\-address\fR=\-
+reads one or more logical block addresses from stdin. These may be comma,
+space, tab or linefeed (newline) separated. If a line contains "#" then
+the remaining characters on that line are ignored. Otherwise each non
+separator sequence of characters should resolve to a decimal number
+unless prefixed by '0x' or '0X' (or has a trailing 'h'). At least one
+address must be given.
+.TP
+\fB\-d\fR, \fB\-\-dummy\fR
+prepare for but do not execute the SCSI REASSIGN BLOCKS command. Since
+the REASSIGN BLOCKS command is essentially irreversible, paranoid
+users may wish to check the invocation of this utility before reassigning
+defective blocks on a disk. Useful with '\-vv' for those who wish to
+view the parameter block that will accompany the command.
+.TP
+\fB\-e\fR, \fB\-\-eight\fR=0 | 1
+when value is 1 then it sets the 'LONGLBA' flag in the command indicating
+that the addresses in the associated parameter block are 8 byte quantities.
+When value is 0 then it clears the 'LONGLBA' flag in the command indicating
+that the addresses in the associated parameter block are 4 byte quantities.
+If this option is not given then 4 byte quantities are assumed unless one
+of the address is too large. 
+.TP
+\fB\-g\fR, \fB\-\-grown\fR
+use the SCSI READ DEFECT DATA (10) command to determine the number of
+elements in the "grown defect list". When this option is given there
+is no reassignment of blocks (i.e. this utility is passive). When this
+option is given then the \fI\-\-address=\fR option is not permitted. See
+the discussion below concerning the relationship between reassigned blocks
+and the grown defect list. This list is sometimes referred to as the GLIST.
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+output the usage message then exit.
+.TP
+\fB\-l\fR, \fB\-\-longlist\fR=0 | 1
+sets the REASSIGN BLOCKS cdb field of the same name to the given value.
+Only 1000 addresses are permitted so there should be no need to specify
+a value of 1. The short list variant restricts the parameter block
+length to 2 ** 16 bytes (i.e. about 16000 4 byte addresses or 8000
+8 byte addresses). Added for completeness.
+.TP
+\fB\-p\fR, \fB\-\-primary\fR
+use the SCSI READ DEFECT DATA (10) command to determine the number of
+elements in the "primary defect list" which is established during the
+manufacturing process. When this option is given there is no reassignment
+of blocks (i.e. this utility is passive). When this option is given then
+the \fI\-\-address=\fR option is not permitted. This list is sometimes
+referred to as the PLIST.
+.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.
+.SH NOTES
+Note that if the ARRE field (for reads) and/or the AWRE field (for writes)
+are set in the "Read Write Error Recovery" mode page then recoverable read
+and/or write errors cause automatic reassignment of the defective block. The
+PER bit in the same mode page controls whether a RECOVERED ERROR sense key
+is reported on not (PER=1 implies do report). Irrespective of the ARRE, AWRE
+or PER field settings, the error counter log pages reflect any
+errors (recovered or otherwise). Whenever a block is reassigned, a new entry
+is added in the "grown" defect list. Apart from doing selftests (see
+sg_senddiag or smartmontools) regularly, monitoring the grown defect list of a disk is
+a reasonable metric of its health. If the grown list starts growing
+quickly that is an ominous sign. The best grown defect lists are empty
+ones. The number of elements in the grown defect list can be viewed with
+the \fI\-\-grown\fR option. The contents of the grown defect list can be
+viewed with the 'sginfo \-G' utility.
+.PP
+If an unrecoverable error is detected at a logical block address then
+REASSIGN BLOCKS is needed to reassign the block. Also if the ARRE and/or
+AWRE fields are clear and a recoverable error is detected then the
+logical block in question may be reassigned with this utility (otherwise
+the error counter log pages will continually be incremented for each
+recovered access).
+.PP
+The number of blocks held in reserve for the purposes of REASSIGN
+BLOCKS is vendor specific and may well be limited to the zone within
+the media where the original (defective) block lay. When this number
+is exhausted subsequent invocations of this utility may result in
+a sense key of hardware error and an additional sense of 'No defect
+spare location available'. The next step would be to reformat the
+disk (or get a replacement).
+.PP
+The SBC\-2 draft standard (revision 16) notes that when multiple addresses
+are given to the SCSI REASSIGN BLOCKS command and there is some failure
+at one of the later addresses then all addresses prior to that have already
+be reassigned. Care should be taken in such a case. Re\-executing the command
+with the same addresses will cause the earlier addresses to be reassigned
+again. At some stage the disk will run out of reserved locations.
+So unless a large number of addresses are involved it may be safer to
+reassign them one address at a time.
+.SH EXIT STATUS
+The exit status of sg_reassign 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 2005\-2007 Douglas Gilbert
+.br
+This software is distributed under a FreeBSD license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg_format,sginfo,sg_senddiag(all in sg3_utils), sdparm(sdparm),
+.B smartmontools(internet, sourceforge)