NAME

       sg_rem_rest_elem - send SCSI remove or restore element command

SYNOPSIS

       sg_rem_rest_elem [--capacity=RC] [--element=EID] [--help] [--quick] [--remove] [--restore] [--timeout=SE]
       [--verbose] [--version] DEVICE

DESCRIPTION

       Sends  a  SCSI REMOVE ELEMENT AND TRUNCATE [RMEAT] or RESTORE ELEMENTS AND REBUILD [RSEAR] command to the
       DEVICE. Since both these commands have a potentially huge impact on the DEVICE  (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.

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

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

OPTIONS

       Arguments to long options are mandatory for short options as well.

       -c, --capacity=RC
              RC stands for Requested Capacity and is the number of logical blocks the DEVICE should have  after
              the  element  is removed with the RMEAT command. The default value is 0 which allows the DEVICE to
              decide what the reduced capacity will be after the element removal. The RSEAR command ignores this
              value.

       -e, --element=EID
              where EID 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 --remove is used.

       -h, --help
              output the usage message then exit.

       -q, --quick
              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 DEVICE.  When this option is given
              that step (i.e. the 15 second warning period) is bypassed.

       -r, --remove
              causes the  REMOVE  ELEMENT  AND  TRUNCATE  command  to  be  sent  to  the  DEVICE.  In  practice,
              --element=EID needs to be also given.

       -R, --restore
              causes the RESTORE ELEMENTS AND REBUILD command to be sent to the DEVICE.

       -t, --timeout=SE
              where  SE  is  the  command timeout in seconds. The default is 60 seconds and if 0 is given, it is
              mapped to 60. An alternate long form is --tmo=SE.

       -v, --verbose
              increase the level of verbosity, (i.e. debug output).

       -V, --version
              print the version string and then exit.

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.

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

EXIT STATUS

       The exit status of sg_rem_rest_elem is 0 when it is successful. Otherwise see the sg3_utils(8) man page.

AUTHORS

       Written by Douglas Gilbert.

REPORTING BUGS

       Report bugs to <dgilbert at interlog dot com>.

COPYRIGHT

       Copyright © 2022-2023 Douglas Gilbert
       This  software  is  distributed  under  a  BSD-2-Clause  license.  There  is  NO  warranty;  not even for
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

SEE ALSO

       sg_get_elem_status,sg_zone(sg3_utils)

sg3_utils-1.48                                      May 2023                                 SG_REM_REST_ELEM(8)