xnu-2782.30.5.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 1916e0fdc8bb51c64ff1f23334ebe313bd8f0150..ce2daefe56713ef3ad3606b4d6374536217a42ea 100644 (file)
--- 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
 .\"    $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
 .\"
 .\"
 .\"     @(#)fcntl.2    8.2 (Berkeley) 1/12/94
 .\"

-.Dd January 12, 1994
+.Dd February 17, 2011

 .Dt FCNTL 2
 .Os BSD 4.2
 .Sh NAME
 .Dt FCNTL 2
 .Os BSD 4.2
 .Sh NAME


@@ -42,12 +65,16 @@
 .Sh SYNOPSIS
 .Fd #include <fcntl.h>
 .Ft int
 .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
 provides for control over descriptors.
 The argument
 .Sh DESCRIPTION
 .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:
 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
 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
 .Xr execv 2

-system calls.
+system call.

 .El
 .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
 .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
 .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
 .It Dv F_GETFL
 Get descriptor status flags, as described below
 .Fa ( arg


@@ -120,8 +145,16 @@ process groups are specified by supplying
 as negative, otherwise 
 .Fa arg
 is interpreted as a process ID.
 as negative, otherwise 
 .Fa arg
 is interpreted as a process ID.

+.It Dv F_GETPATH
+Get the path of the file descriptor 
+.Fa Fildes .  
+The argument must be a buffer of size
+.Sy MAXPATHLEN
+or greater.

 .It Dv F_PREALLOCATE
 .It Dv F_PREALLOCATE

-Preallocate file storage space.
+Preallocate file storage space. Note: upon success, 
+the space that is allocated can be the same size or 
+larger than the space requested.

 .It Dv F_SETSIZE
 Truncate a file without zeroing space.
 The calling process must have root privileges.
 .It Dv F_SETSIZE
 Truncate a file without zeroing space.
 The calling process must have root privileges.


@@ -151,7 +184,63 @@ turns data caching on.
 Get disk device information.
 Currently this only includes the
 disk device address that corresponds
 Get disk device information.
 Currently this only includes the
 disk device address that corresponds

-to the current file offset.
+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 change.
+.It Dv F_LOG2PHYS_EXT
+Variant of F_LOG2PHYS that uses the passed in
+file offset and length.
+.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).
+This is currently implemented on HFS, MS-DOS (FAT),
+and Universal Disk Format (UDF) 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
 .El
 .Pp
 The flags for the


@@ -230,7 +319,7 @@ as well as remove either type of lock
 If a shared or exclusive lock cannot be set,
 .Nm fcntl
 returns immediately with
 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
 .It Dv F_SETLKW
 This command is the same as
 .Dv F_SETLK


@@ -428,15 +517,43 @@ commands operate on the following structure.
 .Pp
 The
 .Dv F_LOG2PHYS
 .Pp
 The
 .Dv F_LOG2PHYS

-command operates on the following structure.
+command operates on the following structure:

 .ne 7v
 .Bd -literal
         struct log2phys {
 .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
         };
 .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
 .Sh RETURN VALUES
 Upon successful completion, the value returned depends on
 .Fa cmd


@@ -458,10 +575,12 @@ Otherwise, a value of -1 is returned and
 .Va errno
 is set to indicate the error.
 .Sh ERRORS
 .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
 .Bl -tag -width Er

-.It Bq Er EACCES
+.\" ==========
+.It Bq Er EAGAIN

 The argument
 .Fa cmd
 is
 The argument
 .Fa cmd
 is


@@ -477,7 +596,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.
 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
 The argument
 .Fa cmd
 is either


@@ -485,6 +604,7 @@ is either
 or
 .Dv F_WRITEBOOTSTRAP
 and the calling process does not have root privileges.
 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.
 .It Bq Er EBADF
 .Fa Fildes
 is not a valid open file descriptor.


@@ -528,27 +648,26 @@ The argument
 .Fa cmd
 is
 .Dv F_LOG2PHYS
 .Fa cmd
 is
 .Dv F_LOG2PHYS

+or
+.Dv F_LOG2PHYS_EXT

 and
 .Fa fildes
 is not a valid file descriptor open for reading.
 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 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 EINTR
 The argument
 .Fa cmd
 is
 .Dv F_SETLKW ,
 and the function was interrupted by a signal.

+.\" ==========

 .It Bq Er EINVAL
 .Fa Cmd
 is
 .It Bq Er EINVAL
 .Fa Cmd
 is


@@ -597,6 +716,14 @@ is either
 or
 .Dv F_WRITEBOOTSTRAP
 and the operation was attempted on a non-HFS disk type.
 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
 .It Bq Er EMFILE
 The argument
 .Fa cmd


@@ -607,6 +734,7 @@ process are already in use,
 or no file descriptors greater than or equal to
 .Fa arg
 are available.
 or no file descriptors greater than or equal to
 .Fa arg
 are available.

+.\" ==========

 .It Bq Er ENOLCK
 The argument
 .Fa cmd
 .It Bq Er ENOLCK
 The argument
 .Fa cmd


@@ -616,6 +744,16 @@ 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.
 .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 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 ESRCH
 .Fa Cmd
 is
 .It Bq Er ESRCH
 .Fa Cmd
 is


@@ -629,6 +767,9 @@ the process ID given as argument is not in use.
 .Xr flock 2 ,
 .Xr getdtablesize 2 ,
 .Xr open 2 ,
 .Xr flock 2 ,
 .Xr getdtablesize 2 ,
 .Xr open 2 ,

+.Xr pipe 2 ,
+.Xr socket 2 ,
+.Xr setsockopt 2 ,

 .Xr sigaction 3
 .Sh HISTORY
 The
 .Xr sigaction 3
 .Sh HISTORY
 The