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 d228a17c17f10988f7efeb5ee01022d56d0a3477..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


@@ -75,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 fildes .
-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 fildes
-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


@@ -131,7 +152,9 @@ The argument must be a buffer of size
 .Sy MAXPATHLEN
 or greater.
 .It Dv F_PREALLOCATE
 .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 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.


@@ -161,7 +184,13 @@ 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
 .It Dv F_FULLFSYNC
 Does the same thing as
 .Xr fsync 2


@@ -175,6 +204,43 @@ 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.
 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


@@ -253,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


@@ -451,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 {
+            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 {
 .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;  /* 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
         };
 .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


@@ -486,7 +580,7 @@ The
 system call will fail if:
 .Bl -tag -width Er
 .\" ==========
 system call will fail if:
 .Bl -tag -width Er
 .\" ==========

-.It Bq Er EACCES
+.It Bq Er EAGAIN

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


@@ -502,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


@@ -554,6 +648,8 @@ 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.


@@ -671,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