sg_unmap - sends a SCSI UNMAP command

NAME

       sg_unmap - sends a SCSI UNMAP command

SYNOPSIS

       sg_unmap      [--anchor]     [--grpnum=GN]     [--help]     [--in=FILE]
       [--lba=LBA,LBA...]   [--num=NUM,NUM...]   [--timeout=TO]    [--verbose]
       [--version] DEVICE

DESCRIPTION

       Send  a  SCSI  UNMAP  command  to  DEVICE  to unmap one or more logical
       blocks. This command was introduced in  SBC-3  revision  18  under  the
       broad  heading  of  "logical  block  provisioning" or more specifically
       "thin provisioning".  Logical blocks may also be unmapped by  the  SCSI
       WRITE  SAME  (16  and  32  byte  cdbs);  see  sg_write_same.  The unmap
       capability is closely related to the ATA DATA  SET  MANAGEMENT  command
       with the "Trim" bit set.

       Logical  blocks  to  be unmapped can be specified in one of two ways to
       this utility. One way is by supplying the (start) LBAs to the  ’--lba=’
       option and the corresponding number(s) to unmap to the ’--num=’ option.
       The other way is by putting (start) LBA and  number  pairs  in  a  file
       whose name is given to the ’--in=’ option. All values are assumed to be
       decimal unless prefixed by "0x" (or "0X") or have a  trailing  "h"  (or
       "H") in which case they are interpreted as hexadecimal.

       When the ’--lba=’ option is given then the ’--num=’ option must also be
       given. If one has a comma separated list as its argument then the other
       must  have  the  same number of elements in its list. The arguments can
       use a single space as a separator but need to be in quotes  or  escaped
       to not be misinterpreted by the shell.

       With  the ’--in=FILE’ option an even number of values must be found and
       are interpreted as pairs: the first value in each pair  is  a  starting
       LBA  and  the  second  value  is  the  number  to  unmap from that LBA.
       Everything from and including a "#" on a line is ignored as  are  blank
       lines.  Values  may  be  comma,  space  and  tab separated or appear on
       separate lines.

OPTIONS

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

-a, --anchor
sets the ’Anchor’ bit in the command (introduced in sbc3r22).

-g, --grpnum=GN
sets the ’Group number’ field to GN. Defaults to a value of
zero. GN should be a value between 0 and 31.

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

-I, --in=FILE
where FILE is a file name containing pairs of values. The first
member of each pair is a starting LBA and the second member of
the pair is the number of logical blocks to unmap from and
including that starting LBA. Values are interpreted as decimal
unless indicated otherwise. This option cannot be present with
the ’--lba=’ option.

-l, --lba=LBA,LBA...
where LBA,LBA... is a string of comma (or space) separated
values that are interpreted as starting logical block addresses.
Each number is interpreted as decimal unless prefixed by ’0x’ or
’0X’ (or it has a trailing ’h’ or ’H’). An argument that
contains any space separators needs to be quoted (or otherwise
escaped). When this option is given then the ’--num=’ option
must also be given and they must contain the same number of
elements in their arguments.

-n, --num=NUM,NUM...
where NUM,NUM... is a string of comma (or space) separated
values that are interpreted as a number of logical blocks to
unmap. Each number is interpreted as decimal unless prefixed by
’0x’ or ’0X’ (or it has a trailing ’h’ or ’H’). Note that 0
blocks is acceptable. An argument that contains any space
separators needs to be quoted (or otherwise escaped). When this
option is given then the ’--lba=’ option must also be given and
they must contain the same number of elements in their
arguments.

-t, --timeout=TO
where TO is a timeout value (in seconds) for the UNMAP command.
The default value is 60 seconds.

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

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

NOTES

       Some limits: an LBA can be up to 64 bits, a NUM up to 32 bits  (imposed
       by  structure of UNMAP SCSI command parameter data). The NUM is further
       constrained by the MAXIMUM UNMAP LBA COUNT field in  the  BLOCK  LIMITS
       VPD  page (0xb0). The maximum number of LBA,NUM pairs is limited to 128
       by this utility and may be further constrained  by  the  MAXIMUM  UNMAP
       BLOCK DESCRIPTOR COUNT field in the BLOCK LIMITS VPD page.

       Since  it  is unclear how long the UNMAP command will take to execute a
       ’--timeout=" option has been provided. The default timeout period is 60
       seconds.  If  all  the  logical  blocks on a logical unit (e.g.  a disk
       drive) are to be unmapped then the FORMAT UNIT SCSI  command  (see  the
       sg_format utility) may be considered as an alternative.

       Support  for  thin  provisioning  is  indicated  by  the TPE bit in the
       response to the SCSI READ CAPACITY (16)  command  (see  the  sg_readcap
       utility).

       In  the  examples  directory  of  the  sg3_utils  package  there  is  a
       sg_unmap_example.txt file that shows the format that the ’--in=’ option
       accepts.

EXIT STATUS

       The  exit  status of sg_unmap 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 © 2009-2010 Douglas Gilbert
       This software is distributed under  a  FreeBSD  license.  There  is  NO
       warranty;  not  even  for  MERCHANTABILITY  or FITNESS FOR A PARTICULAR
       PURPOSE.