167 lines
7.8 KiB
Groff
167 lines
7.8 KiB
Groff
.TH SG_UNMAP "8" "March 2018" "sg3_utils\-1.43" SG3_UTILS
|
|
.SH NAME
|
|
sg_unmap \- send SCSI UNMAP command (known as 'trim' in ATA specs)
|
|
.SH SYNOPSIS
|
|
.B sg_unmap
|
|
[\fI\-\-all=ST,RN[,LA]\fR] [\fI\-\-anchor\fR] [\fI\-\-dry\-run\fR]
|
|
[\fI\-\-force\fR] [\fI\-\-grpnum=GN\fR] [\fI\-\-help\fR] [\fI\-\-in=FILE\fR]
|
|
[\fI\-\-lba=LBA,LBA...\fR] [\fI\-\-num=NUM,NUM...\fR] [\fI\-\-timeout=TO\fR]
|
|
[\fI\-\-verbose\fR] [\fI\-\-version\fR] \fIDEVICE\fR
|
|
.SH DESCRIPTION
|
|
.\" Add any additional description here
|
|
.PP
|
|
Send a SCSI UNMAP command to \fIDEVICE\fR to unmap one or more logical
|
|
blocks. This command was introduced in SBC\-3 revision 18 under the broad
|
|
heading of "logical block provisioning". Logical blocks may also be unmapped
|
|
by the SCSI WRITE SAME command; see the sg_write_same utility. The unmap
|
|
capability is closely related to the ATA DATA SET MANAGEMENT command with
|
|
the "Trim" bit set.
|
|
.PP
|
|
Logical blocks to be unmapped can be specified in one of three 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. Another
|
|
way is by putting start LBA and number to unmap pairs in a file whose name
|
|
is given to the '\-\-in=' option. Alternatively a large segment or all of
|
|
a disk (SSD) can be unmapped with the \fI\-\-all=ST_RN[,LA]\fR 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.
|
|
Suffix multipliers are permitted on decimal values (e.g. '\-\-num=1m').
|
|
.PP
|
|
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.
|
|
.PP
|
|
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. Each line should
|
|
not exceed 1023 bytes in length.
|
|
.PP
|
|
Since a lot of data can be lost with this utility, a 15 second "cooling off"
|
|
period is given before any UNMAP commands are sent. During this period the
|
|
user is reminded what will happen, and to which device, so they can use
|
|
control\-C (or some other technique) to terminate this utility before any
|
|
unmapping takes place. This period can be bypassed with the \fI\-\-force\fR
|
|
option.
|
|
.SH OPTIONS
|
|
Arguments to long options are mandatory for short options as well.
|
|
.TP
|
|
\fB\-A\fR, \fB\-\-all\fR=\fIST,RN[,LA]\fR
|
|
where \fIST\fR is the starting LBA, \fIRN\fR is the repeat number which is
|
|
the maximum number of blocks in each SCSI UNMAP command, and \fILA\fR, if
|
|
given, is the last LBA to unmap. If \fILA\fR is not given, then the last
|
|
LBA on the \fIDEVICE\fR is used. That is obtained by the SCSI READ CAPACITY
|
|
command.
|
|
.TP
|
|
\fB\-a\fR, \fB\-\-anchor\fR
|
|
sets the 'Anchor' bit in the command (introduced in sbc3r22).
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-dry\-run\fR
|
|
perform all the preparation, including opening \fIDEVICE\fR plus sending
|
|
a 'standard' SCSI INQUIRY command (and optionally a READ CAPACITY), but
|
|
exit before performing any SCSI UNMAP commands.
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-force\fR
|
|
bypass the 15 second warning period that occurs before any UNMAP commands
|
|
are sent.
|
|
.TP
|
|
\fB\-g\fR, \fB\-\-grpnum\fR=\fIGN\fR
|
|
sets the 'Group number' field to \fIGN\fR. Defaults to a value of zero.
|
|
\fIGN\fR should be a value between 0 and 63.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
output the usage message then exit.
|
|
.TP
|
|
\fB\-I\fR, \fB\-\-in\fR=\fIFILE\fR
|
|
where \fIFILE\fR 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.
|
|
.TP
|
|
\fB\-l\fR, \fB\-\-lba\fR=\fILBA,LBA...\fR
|
|
where \fILBA,LBA...\fR 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.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-num\fR=\fINUM,NUM...\fR
|
|
where \fINUM,NUM...\fR 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.
|
|
.TP
|
|
\fB\-t\fR, \fB\-\-timeout\fR=\fITO\fR
|
|
where \fITO\fR is a timeout value (in seconds) for the UNMAP command.
|
|
The default value is 60 seconds.
|
|
.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
|
|
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.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Support for logical block provisioning is indicated by the LBPME bit in the
|
|
response to the SCSI READ CAPACITY (16) command (see the sg_readcap utility).
|
|
.PP
|
|
In SBC\-3 revision 25 the LBPU and ANC_SUP bits where added to the
|
|
Logical Block Provisioning VPD page. When LBPU is set it indicates that
|
|
the device supports the UNMAP command. When the ANC_SUP bit is set it
|
|
indicates the device supports anchored LBAs.
|
|
.PP
|
|
The SCSI UNMAP command does the "right thing" with respect to command
|
|
queueing. However its ATA counterpart: the DATA SET MANAGEMENT command with
|
|
the "Trim" bit set does not interact well with SATA queueing known as NCQ.
|
|
To address this problem T13 have introduced a new command called SFQ DATA SET
|
|
MANAGEMENT which also has a Trim bit.
|
|
.SH EXAMPLES
|
|
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.
|
|
.PP
|
|
To unmap all blocks from and including LBA 0x2000 to the end of the
|
|
device (e.g. disk or SSD) with each SCSI UNMAP command given 1024
|
|
blocks to unmap:
|
|
.PP
|
|
sg_unmap \-\-all=0x2000,1k /dev/sg2
|
|
.PP
|
|
Add '\-\-force' to bypass the 15 seconds of warnings. So '\-\-force' is
|
|
appropriate for batch files.
|
|
.SH EXIT STATUS
|
|
The exit status of sg_unmap 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 2009\-2018 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,sg_get_lba_status,sg_readcap,sg_vpd,sg_write_same(sg3_utils)
|