add sg_unmap

git-svn-id: https://svn.bingwo.ca/repos/sg3_utils/trunk@273 6180dd3e-e324-4e3e-922d-17de1ae2f315

1 files changed, 117 insertions, 0 deletions

diff --git a/doc/sg_unmap.8 b/doc/sg_unmap.8
new file mode 100644
index 00000000..08e12316
--- /dev/null
+++ b/doc/sg_unmap.8
@@ -0,0 +1,117 @@
+.TH SG_UNMAP "8" "June 2009" "sg3_utils\-1.28" SG3_UTILS
+.SH NAME
+sg_unmap \- sends a SCSI UNMAP command
+.SH SYNOPSIS
+.B sg_unmap
+[\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. 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.
+.PP
+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.
+.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.
+.SH OPTIONS
+Arguments to long options are mandatory for short options as well.
+.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 31.
+.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 thin provisioning is indicated by the TPE bit in the response
+to the SCSI READ CAPACITY (16) command (see the sg_readcap utility).
+.PP
+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.
+.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 Douglas Gilbert
+.br
+This software is distributed under a FreeBSD license. There is NO
+warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+.SH "SEE ALSO"
+.B sg_format,sg_readcap,sg_write_same(sg3_utils)