diff options
Diffstat (limited to 'doc/sg_unmap.8')
| -rw-r--r-- | doc/sg_unmap.8 | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/doc/sg_unmap.8 b/doc/sg_unmap.8 new file mode 100644 index 00000000..b72ecb05 --- /dev/null +++ b/doc/sg_unmap.8 @@ -0,0 +1,166 @@ +.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) |