xnu-4570.61.1.tar.gz

[apple/xnu.git] / bsd / man / man2 / fcntl.2

diff --git a/bsd/man/man2/fcntl.2 b/bsd/man/man2/fcntl.2
index ce2daefe56713ef3ad3606b4d6374536217a42ea..0ea25179c6e033869a4df1192cc15d16f39b8b8e 100644 (file)
--- a/bsd/man/man2/fcntl.2
+++ b/bsd/man/man2/fcntl.2
@@ -56,7 +56,7 @@
 .\"
 .\"     @(#)fcntl.2    8.2 (Berkeley) 1/12/94
 .\"
-.Dd February 17, 2011
+.Dd August 24, 2017
 .Dt FCNTL 2
 .Os BSD 4.2
 .Sh NAME
@@ -71,7 +71,7 @@
 .Fa "..."
 .Fc
 .Sh DESCRIPTION
-.Fn Fcntl
+.Fn fcntl
 provides for control over descriptors.
 The argument
 .Fa fildes
@@ -153,8 +153,16 @@ The argument must be a buffer of size
 or greater.
 .It Dv F_PREALLOCATE
 Preallocate file storage space. Note: upon success, 
-the space that is allocated can be the same size or 
-larger than the space requested.
+the space that is allocated can be the size requested,
+larger than the size requested, or (if the
+.Dv F_ALLOCATEALL
+flag is not provided) smaller than the space requested.
+.It Dv F_PUNCHHOLE
+Deallocate a region and replace it with a hole. Subsequent reads of the
+affected region will return bytes of zeros that are usually not backed by
+physical blocks. This will not change the actual file size. Holes must be
+aligned to file system block boundaries. This will fail on
+file systems that do not support this interface.
 .It Dv F_SETSIZE
 Truncate a file without zeroing space.
 The calling process must have root privileges.
@@ -182,11 +190,11 @@ A value of zero in
 turns data caching on.
 .It Dv F_LOG2PHYS
 Get disk device information.
-Currently this only includes the
+Currently this only returns the
 disk device address that corresponds
-to the current file offset. Note that if the
-file offset is not backed by physical blocks
-we can return -1 as the offset. This is subject
+to the current file offset. Note that the system 
+may return -1 as the disk device address if the file is not 
+backed by physical blocks. This is subject
 to change.
 .It Dv F_LOG2PHYS_EXT
 Variant of F_LOG2PHYS that uses the passed in
@@ -491,6 +499,19 @@ Allocate from the volume offset.
 .El
 .Pp
 The
+.Dv F_PUNCHHOLE
+command operates on the following structure:
+.ne 7v
+.Bd -literal
+        typedef struct fpunchhole {
+            u_int32_t fp_flags;     /* unused */
+            u_int32_t reserved;     /* (to maintain 8-byte alignment) */
+            off_t     fp_offset;    /* IN: start of the region */
+            off_t     fp_length;    /* IN: size of the region */
+        } fpunchhole_t;
+.Ed
+.Pp
+The
 .Dv F_RDADVISE
 command operates on the following structure
 which holds information passed from the
@@ -711,6 +732,21 @@ is a negative or zero value.
 .Pp
 The argument
 .Fa cmd
+is
+.Dv F_PUNCHHOLE
+and
+either
+.Fa fp_offset
+or
+.Fa fp_length
+are negative, or both
+.Fa fp_offset
+and
+.Fa fp_length
+are not multiples of the file system block size.
+.Pp
+The argument
+.Fa cmd
 is either
 .Dv F_READBOOTSTRAP
 or
@@ -745,6 +781,31 @@ or
 and satisfying the lock or unlock request would result in the
 number of locked regions in the system exceeding a system-imposed limit.
 .\" ==========
+.It Bq Er ENOSPC
+The argument
+.Fa cmd
+is
+.Dv F_PREALLOCATE
+and either there is no space available on the volume containing
+.Fa fildes
+or
+.Fa fst_flags
+contains
+.Dv F_ALLOCATEALL
+and there is not enough space available on the volume containing
+.Fa fildes
+to satisfy the entire request.
+.Pp
+The argument
+.Fa cmd
+is
+.Dv F_PUNCHHOLE
+and there is not enough space available on the volume containing
+.Fa fildes
+to satisfy the request. As an example, a filesystem that supports
+cloned files may return this error if punching a hole requires the
+creation of a clone and there is not enough space available to do so.
+.\" ==========
 .It Bq Er EOVERFLOW
 A return value would overflow its representation.
 For example,
@@ -754,6 +815,11 @@ and the smallest (or, if l_len is non-zero, the largest) offset
 of a byte in the requested segment
 will not fit in an object of type off_t.
 .\" ==========
+.It Bq Er EPERM
+The argument cmd is
+.Dv F_PUNCHHOLE
+and the calling process does not have file write permission.
+.\" ==========
 .It Bq Er ESRCH
 .Fa Cmd
 is