X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/9bccf70c0258c7cac2dcb80011b2a964d884c552..c3c9b80d004dbbfdf763edeb97968c6997e3b45b:/bsd/man/man2/fcntl.2

diff --git a/bsd/man/man2/fcntl.2 b/bsd/man/man2/fcntl.2
index 1916e0fdc..519bb1e0b 100644
--- a/bsd/man/man2/fcntl.2
+++ b/bsd/man/man2/fcntl.2
@@ -1,3 +1,26 @@
+.\"
+.\" Copyright (c) 2011 Apple Inc.  All rights reserved.
+.\"
+.\" @APPLE_LICENSE_HEADER_START@
+.\" 
+.\" This file contains Original Code and/or Modifications of Original Code
+.\" as defined in and that are subject to the Apple Public Source License
+.\" Version 2.0 (the 'License'). You may not use this file except in
+.\" compliance with the License. Please obtain a copy of the License at
+.\" http://www.opensource.apple.com/apsl/ and read it before using this
+.\" file.
+.\" 
+.\" The Original Code and all software distributed under the License are
+.\" distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
+.\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
+.\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
+.\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
+.\" Please see the License for the specific language governing rights and
+.\" limitations under the License.
+.\" 
+.\" @APPLE_LICENSE_HEADER_END@
+.\"
+.\"
 .\"	$NetBSD: fcntl.2,v 1.6 1995/02/27 12:32:29 cgd Exp $
 .\"
 .\" Copyright (c) 1983, 1993
@@ -33,7 +56,7 @@
 .\"
 .\"     @(#)fcntl.2	8.2 (Berkeley) 1/12/94
 .\"
-.Dd January 12, 1994
+.Dd August 8, 2018
 .Dt FCNTL 2
 .Os BSD 4.2
 .Sh NAME
@@ -42,12 +65,16 @@
 .Sh SYNOPSIS
 .Fd #include <fcntl.h>
 .Ft int
-.Fn fcntl "int fd" "int cmd" "int arg"
+.Fo fcntl
+.Fa "int fildes"
+.Fa "int cmd"
+.Fa "..."
+.Fc
 .Sh DESCRIPTION
-.Fn Fcntl
+.Fn fcntl
 provides for control over descriptors.
 The argument
-.Fa fd
+.Fa fildes
 is a descriptor to be operated on by
 .Fa cmd
 as follows:
@@ -71,26 +98,24 @@ Same file status flags (i.e., both file descriptors
 share the same file status flags).
 .It
 The close-on-exec flag associated with the new file descriptor
-is set to remain open across
+is cleared so that the descriptor remains open across an
 .Xr execv 2
-system calls.
+system call.
 .El
+.It Dv F_DUPFD_CLOEXEC
+Like
+.Dv F_DUPFD ,
+except that the close-on-exec flag associated with the new file descriptor
+is set.
 .It Dv F_GETFD
-Get the close-on-exec flag associated with the file descriptor
-.Fa fd .
-If the low-order bit of the returned value is 0,
-the file will remain open across
-.Fn exec ,
-otherwise the file will be closed upon execution of
-.Fn exec
+Get the flags associated with the file descriptor
+.Fa fildes ,
+as described below
 .Fa ( arg
 is ignored).
 .It Dv F_SETFD
-Set the close-on-exec flag associated with
-.Fa fd
-to the low order bit of
-.Fa arg
-(0 or 1 as above).
+Set the file descriptor flags to
+.Fa arg .
 .It Dv F_GETFL
 Get descriptor status flags, as described below
 .Fa ( arg
@@ -120,11 +145,33 @@ process groups are specified by supplying
 as negative, otherwise 
 .Fa arg
 is interpreted as a process ID.
+.It Dv F_GETPATH
+Get the path of the file descriptor
+.It Dv F_GETPATH_NOFIRMLINK
+Get the non firmlinked path of the file descriptor
+.Fa Fildes .  
+The argument must be a buffer of size
+.Sy MAXPATHLEN
+or greater.
 .It Dv F_PREALLOCATE
-Preallocate file storage space.
+Preallocate file storage space. Note: upon success, 
+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.
+Deprecated.
+In previous releases, this would allow a process with root privileges to
+truncate a file without zeroing space.
+For security reasons, this operation is no longer supported and will
+instead truncate the file in the same manner as
+.Xr truncate 2 .
 .It Dv F_RDADVISE
 Issue an advisory read async with no copy to user.
 .It Dv F_RDAHEAD
@@ -135,11 +182,6 @@ disables read ahead.
 A non-zero value in
 .Fa arg
 turns read ahead on.
-.It Dv F_READBOOTSTRAP
-Read bootstrap from disk.
-.It Dv F_WRITEBOOTSTRAP
-Write bootstrap on disk.
-The calling process must have root privileges.
 .It Dv F_NOCACHE
 Turns data caching off/on. A non-zero value in
 .Fa arg
@@ -149,9 +191,91 @@ 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.
+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
+file offset and length.
+.It Dv F_BARRIERFSYNC
+Does the same thing as
+.Xr fsync 2
+then issues a barrier command to the drive
+.Fa ( arg
+is ignored).
+The barrier applies to I/O that have been flushed with
+.Xr fsync 2
+on the same device before.  These operations are guaranteed to
+be persisted before any other I/O that would follow the barrier,
+although no assumption should be made on what has been persisted
+or not when this call returns.  After the barrier has been issued,
+operations on other FDs that have been fsync'd before can still be
+re-ordered by the device, but not after the barrier.  This is
+typically useful to guarantee valid state on disk when ordering is a
+concern but durability is not.  A barrier can be used to order two phases of operations on
+a set of file descriptors and ensure that no file can possibly get persisted
+with the effect of the second phase without the effect of the first one. To do so,
+execute operations of phase one, then
+.Xr fsync 2
+each FD and issue a single barrier.  Finally execute operations of phase two.
+This is currently implemented on HFS and APFS. It requires hardware support,
+which Apple SSDs are guaranteed to provide.
+.It Dv F_FULLFSYNC
+Does the same thing as
+.Xr fsync 2
+then asks the drive to
+flush all buffered data to
+the permanent storage device
+.Fa ( arg
+is ignored).
+As this drains the entire queue of the device and acts as a
+barrier, data that had been fsync'd on the same device before
+is guaranteed to be persisted when this call returns.
+This is currently implemented on HFS, MS-DOS (FAT),
+Universal Disk Format (UDF) and APFS file systems.
+The operation may take quite a while to complete.
+Certain FireWire drives have also been known
+to ignore the request to flush their buffered data.
+.It Dv F_SETNOSIGPIPE
+Determines whether a
+.Dv SIGPIPE
+signal will be generated when a write fails on a pipe or socket for
+which there is no reader.  If
+.Fa arg
+is non-zero,
+.Dv SIGPIPE
+generation is disabled for descriptor
+.Fa fildes ,
+while an
+.Fa arg
+of zero enables it (the default).
+.It Dv F_GETNOSIGPIPE
+Returns whether a
+.Dv SIGPIPE
+signal will be generated when a write fails on a pipe or socket
+for which there is no reader.  The semantics of the return value
+match those of the
+.Fa arg
+of
+.Dv F_SETNOSIGPIPE .
+.El
+.Pp
+The flags for the
+.Dv F_GETFD
+and
+.Dv F_SETFD
+commands are as follows:
+.Bl -tag -width FD_CLOEXECX -offset indent
+.It Dv FD_CLOEXEC
+Close-on-exec; the given file descriptor will be automatically
+closed in the successor process image when one of the
+.Xr execv 2
+or
+.Xr posix_spawn 2
+family of system calls is invoked.
 .El
 .Pp
 The flags for the
@@ -230,7 +354,7 @@ as well as remove either type of lock
 If a shared or exclusive lock cannot be set,
 .Nm fcntl
 returns immediately with
-.Er EACCES .
+.Er EAGAIN .
 .It Dv F_SETLKW
 This command is the same as
 .Dv F_SETLK
@@ -397,11 +521,27 @@ The modes are as follows:
 .Bl -tag -width F_PEOFPOSMODEX -offset indent
 .It Dv F_PEOFPOSMODE
 Allocate from the physical end of file.
+In this case,
+.Fa fst_length
+indicates the number of newly allocated bytes desired.
 .It Dv F_VOLPOSMODE
 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
@@ -428,15 +568,43 @@ commands operate on the following structure.
 .Pp
 The
 .Dv F_LOG2PHYS
-command operates on the following structure.
+command operates on the following structure:
 .ne 7v
 .Bd -literal
         struct log2phys {
-	    u_int32_t	l2p_flags;		/* unused so far */
-	    off_t	l2p_contigbytes;	/* unused so far */
-	    off_t	l2p_devoffset;	    /* bytes into device */
+            u_int32_t l2p_flags;        /* unused so far */
+            off_t     l2p_contigbytes;  /* unused so far */
+            off_t     l2p_devoffset;    /* bytes into device */
         };
 .Ed
+.Pp
+The
+.Dv F_LOG2PHYS_EXT
+command operates on the same structure as F_LOG2PHYS but treats it as an in/out:
+.ne 7v
+.Bd -literal
+        struct log2phys {
+            u_int32_t l2p_flags;        /* unused so far */
+            off_t     l2p_contigbytes;  /* IN: number of bytes to be queried;
+                                           OUT: number of contiguous bytes allocated at this position */
+            off_t     l2p_devoffset;    /* IN: bytes into file;
+                                           OUT: bytes into device */
+        };
+.Ed
+.Pp
+If
+.Fa fildes
+is a socket, then the
+.Dv F_SETNOSIGPIPE
+and
+.Dv F_GETNOSIGPIPE
+commands are directly analogous, and fully interoperate with the
+.Dv SO_NOSIGPIPE
+option of
+.Xr setsockopt 2
+and
+.Xr getsockopt 2
+respectively.
 .Sh RETURN VALUES
 Upon successful completion, the value returned depends on
 .Fa cmd
@@ -458,10 +626,12 @@ Otherwise, a value of -1 is returned and
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
-.Fn Fcntl
-will fail if:
+The
+.Fn fcntl
+system call will fail if:
 .Bl -tag -width Er
-.It Bq Er EACCES
+.\" ==========
+.It Bq Er EAGAIN
 The argument
 .Fa cmd
 is
@@ -477,7 +647,7 @@ exclusive-locked by another process;
 or the type is an exclusive lock and some portion of the
 segment of a file to be locked is already shared-locked or
 exclusive-locked by another process.
-.Pp
+.It Bq Er EACCESS
 The argument
 .Fa cmd
 is either
@@ -485,6 +655,7 @@ is either
 or
 .Dv F_WRITEBOOTSTRAP
 and the calling process does not have root privileges.
+.\" ==========
 .It Bq Er EBADF
 .Fa Fildes
 is not a valid open file descriptor.
@@ -528,27 +699,26 @@ The argument
 .Fa cmd
 is
 .Dv F_LOG2PHYS
+or
+.Dv F_LOG2PHYS_EXT
 and
 .Fa fildes
 is not a valid file descriptor open for reading.
-.It Bq Er EMFILE
-.Fa Cmd
-is
-.Dv F_DUPFD
-and the maximum allowed number of file descriptors are currently
-open.
+.\" ==========
 .It Bq Er EDEADLK
 The argument
 .Fa cmd
 is
 .Dv F_SETLKW ,
 and a deadlock condition was detected.
+.\" ==========
 .It Bq Er EINTR
 The argument
 .Fa cmd
 is
 .Dv F_SETLKW ,
 and the function was interrupted by a signal.
+.\" ==========
 .It Bq Er EINVAL
 .Fa Cmd
 is
@@ -592,11 +762,34 @@ 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
 .Dv F_WRITEBOOTSTRAP
 and the operation was attempted on a non-HFS disk type.
+.\" ==========
+.It Bq Er EMFILE
+.Fa Cmd
+is
+.Dv F_DUPFD
+and the maximum allowed number of file descriptors are currently
+open.
+.\" ==========
 .It Bq Er EMFILE
 The argument
 .Fa cmd
@@ -607,6 +800,7 @@ process are already in use,
 or no file descriptors greater than or equal to
 .Fa arg
 are available.
+.\" ==========
 .It Bq Er ENOLCK
 The argument
 .Fa cmd
@@ -616,6 +810,46 @@ or
 .Dv F_SETLKW ,
 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,
+.Fa cmd
+is F_GETLK, F_SETLK, or F_SETLKW
+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
@@ -629,6 +863,9 @@ the process ID given as argument is not in use.
 .Xr flock 2 ,
 .Xr getdtablesize 2 ,
 .Xr open 2 ,
+.Xr pipe 2 ,
+.Xr socket 2 ,
+.Xr setsockopt 2 ,
 .Xr sigaction 3
 .Sh HISTORY
 The