doc/sg_reassign.8

.TH SG_REASSIGN "8" "October 2019" "sg3_utils\-1.45" SG3_UTILS
.SH NAME
sg_reassign \- send 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\-\-hex\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.
The options are arranged in alphabetical order based on the long
option name.
.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 or a (single) space. A string that contains
any space separators needs to be quoted. 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. Lines should not be longer than 1023 bytes.
.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\-H\fR, \fB\-\-hex\fR
print response in hex (for \fB\-g\fR, \fB\-\-grown\fR, \fB\-p\fR
or \fB\-\-primary\fR).
.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\-2019 Douglas Gilbert
.br
This software is distributed under a BSD\-2\-Clause 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)