+.\"
+.\" 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
.\"
.\" @(#)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
.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
-.Fa fd
+.Fa fildes
is a descriptor to be operated on by
.Fa cmd
as follows:
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
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
-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.
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
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
.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
.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
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
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.
.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
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
or no file descriptors greater than or equal to
.Fa arg
are available.
+.\" ==========
.It Bq Er ENOLCK
The argument
.Fa cmd
.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
.Xr flock 2 ,
.Xr getdtablesize 2 ,
.Xr open 2 ,
+.Xr pipe 2 ,
+.Xr socket 2 ,
+.Xr setsockopt 2 ,
.Xr sigaction 3
.Sh HISTORY
The
projects / apple / xnu.git / blobdiff