diff options
Diffstat (limited to 'doc/sg_rem_rest_elem.8')
-rw-r--r-- | doc/sg_rem_rest_elem.8 | 95 |
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/sg_rem_rest_elem.8 b/doc/sg_rem_rest_elem.8 new file mode 100644 index 00000000..13ef9c1a --- /dev/null +++ b/doc/sg_rem_rest_elem.8 @@ -0,0 +1,95 @@ +.TH SG_REM_REST_ELEM "8" "June 2022" "sg3_utils\-1.48" SG3_UTILS +.SH NAME +sg_rem_rest_elem \- send SCSI remove or restore element command +.SH SYNOPSIS +.B sg_rem_rest_elem +[\fI\-\-capacity=RC\fR] [\fI\-\-element=EID\fR] [\fI\-\-help\fR] +[\fI\-\-quick\fR] [\fI\-\-remove\fR] [\fI\-\-restore\fR] [\fI\-\-verbose\fR] +[\fI\-\-version\fR] \fIDEVICE\fR +.SH DESCRIPTION +.\" Add any additional description here +.PP +Sends a SCSI REMOVE ELEMENT AND TRUNCATE [RMEAT] or RESTORE ELEMENTS AND +REBUILD [RSEAR] command to the \fIDEVICE\fR. Since both these commands have +a potentially huge impact on the \fIDEVICE\fR (similar to the FORMAT UNIT +command: destroying data and taking a long time to complete fully), +they first give the user the chance to reconsider (3 times within 15 +seconds) before taking action. +.PP +Unlike the FORMAT UNIT command, these commands seem designed to work in +the background. So they will return quickly (although sbc5r01.pdf does not +state that) and the disk will be placed in a reduced functionality state +where only a specified number of commands will be executed (e.g. INQUIRY and +REPORT LUNS) until the operation is complete. Other commands will receive +sense data with a sense key of NOT READY and an additional sense code +of 'Depopulation in progress' (for RMEAT) or 'Depopulation restoration in +progress' (for RSEAR). +.PP +The REMOVE ELEMENT AND TRUNCATE has a close relative in ZBC\-2 called the +REMOVE ELEMENT AND MODIFY ZONES [RMEMZ] command. See the sg_zone utility +for an implementation of the latter command. +.br +The difference between RMEAT and RMEMZ is that the former "changes the +association between LBAs and physical blocks" and the latter does not +change that association. Zones affected by the RMEMZ command are placed +into the zone condition: "Offline". +.SH OPTIONS +Arguments to long options are mandatory for short options as well. +.TP +\fB\-c\fR, \fB\-\-capacity\fR=\fIRC\fR +RC stands for Requested Capacity and is the number of logical blocks the +\fIDEVICE\fR should have after the element is removed with the RMEAT +command. The default value is 0 which allows the \fIDEVICE\fR to decide +what the reduced capacity will be after the element removal. The RSEAR +command ignores this value. +.TP +\fB\-e\fR, \fB\-\-element\fR=\fIEID\fR +where \fIEID\fR is an element identifier which is a 32 bit unsigned integer +starting at one. This field is used by the RMEAT command and ignored +otherwise. The default value is zero (which is invalid). So the user needs +to supply a valid element identifier when \fI\-\-remove\fR is used. +.TP +\fB\-h\fR, \fB\-\-help\fR +output the usage message then exit. +.TP +\fB\-q\fR, \fB\-\-quick\fR +the default action (i.e. when this option is not given) is to give the user +15 seconds to reconsider doing a remove or restore element operation on the +\fIDEVICE\fR. When this option is given that step (i.e. the 15 second +warning period) is bypassed. +.TP +\fB\-r\fR, \fB\-\-remove\fR +causes the REMOVE ELEMENT AND TRUNCATE command to be sent to the +\fIDEVICE\fR. In practice, \fI\-\-element=EID\fR needs to be also given. +.TP +\fB\-R\fR, \fB\-\-restore\fR +causes the RESTORE ELEMENTS AND REBUILD command to be sent to the +\fIDEVICE\fR. +.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 +Once an element is removed successfully it is termed as "depopulated". +Depopulated elements that have the 'Restoration Allowed' (RALWD) bit +set (see sg_get_elem_status) are candidates for future restoration. +.PP +A (storage) element of a rotating hard disk is one side of a platter +typically associated with one head. Such hard disks typically have multiple +platters with two heads per platter (i.e. one head each side of the platter). +.SH EXIT STATUS +The exit status of sg_rem_rest_elem 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 2022 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_get_elem_status,sg_zone(sg3_utils) |