Differences between current version and revision by previous author of fcntl(2).
Other diffs: Previous Major Revision, Previous Revision, or view the Annotated Edit History
| Newer page: | version 4 | Last edited on Sunday, November 3, 2002 3:12:33 pm | by PerryLorier | |
| Older page: | version 2 | Last edited on Tuesday, June 4, 2002 12:23:40 am | by perry | Revert |
@@ -1,372 +1,194 @@
-FCNTL
-!!!FCNTL
-NAME
-SYNOPSIS
-DESCRIPTION
-RETURN VALUE
-ERRORS
-NOTES
-CONFORMING TO
-SEE ALSO
-----
!!NAME
+fcntl - manipulate file descriptor
-
-fcntl - manipulate file descriptor
!!SYNOPSIS
+ __#include <unistd.h>__
+ __#include <fcntl.h>__ /* for fcntl(2) prototype */
+ __int fcntl(int__ ''fd''__, int__ ''cmd''__);__
+ __int fcntl(int__ ''fd''__, int__ ''cmd''__, long__ ''arg''__);__
+ __int fcntl(int__ ''fd''__, int__ ''cmd''__, struct flock *__''lock''__);__
-
-__#include
-__ ''fd''__, int__ ''cmd''__);
-int fcntl(int__ ''fd''__, int__ ''cmd''__, long__ ''arg''__);
-int fcntl(int__ ''fd''__, int__ ''cmd''__, struct flock *__''lock''__);
-__
!!DESCRIPTION
+fcntl(2) performs one of various miscellaneous operations on ''fd''. The operation in question is determined by ''cmd'':
+;__F_DUPFD__: Find the lowest numbered available file descriptor greater than or equal to ''arg'' and make it be a copy of ''fd''. This is different form dup2(2) which uses exactly the descriptor specified.
-__fcntl__ performs one of various miscellaneous
-operations on ''fd''.
The operation in question
is
-determined
by ''cmd'':
+;:
The old and new descriptors may be used interchangeably. They share locks, file position pointers and flags; for example, if the file position
is modified
by using lseek(2) on one of the descriptors, the position is also changed for the other.
+;:The two descriptors do not share the close-on-exec flag, however. The close-on-exec flag of the copy is off, meaning that it will not be closed on exec.
-__F_DUPFD__
+;:On success, the new descriptor is returned.
+;__F_GETFD__: Read the close-on-exec flag. If the __FD_CLOEXEC__ bit is 0, the file will remain open across execve(2), otherwise it will be closed.
-Find
the lowest numbered available file descriptor greater
-than or equal
to ''arg'' and make it be a copy of
-''fd''. This is different form dup2(2) which uses
-exactly the descriptor specified
.
+;__F_SETFD__: Set
the close-on-exec flag
to the value specified by the __FD_CLOEXEC__ bit of
''arg''.
+;__F_GETFL__: Read the descriptor's flags (all flags (as set by open(2)) are returned).
-The old and new descriptors may be used interchangeably.
-They share locks, file position pointers and flags
; for
-example, if
the file position is modified
by using
-lseek
__ on one of the descriptors
, the position is also
-changed for
the other.
+;__F_SETFL__: Set
the descriptor's flags to the value specified
by ''arg''. Only
__O_APPEND
__, __O_NONBLOCK__ and __O_ASYNC__ may be set;
the other flags are unaffected
.
+;:The flags are shared between copies (made with dup(2), fork(2), etc.) of the same file descriptor.
-The two descriptors do not share the close-on-exec flag,
-however. The close-on-exec flag of the copy is off, meaning
-that it will not be closed on exec
.
+;:
The flags and their semantics are described in open(2)
.
+__F_GETLK__, __F_SETLK__ and __F_SETLKW__ are used to manage discretionary file locks. The third argument ''lock'' is a pointer to a struct flock (that may be overwritten by this call).
-On success
, the new descriptor
is returned
.
+;__F_GETLK__: Return the flock structure that prevents us from obtaining the lock
, or set the __l_type__ field of
the lock to __F_UNLCK__ if there
is no obstruction
.
-
-__F_GETFD__
-
-
-Read the close-on-exec flag. If the __FD_CLOEXEC__ bit is
-, the file will remain open across __exec__, otherwise
-it will be closed.
-
-
-__F_SETFD__
-
-
-Set the close-on-exec flag to the value specified by the
-__FD_CLOEXEC__ bit of ''arg''.
-
-
-__F_GETFL__
-
-
-Read the descriptor's flags (all flags (as set by
-open(2)) are returned).
-
-
-__F_SETFL__
-
-
-Set the descriptor's flags to the value specified by
-''arg''. Only __O_APPEND__, __O_NONBLOCK__ and
-__O_ASYNC__ may be set
; the other flags are
-unaffected.
-
-
-The flags are shared between copies (made with
-dup(2), fork(2), etc.) of the same file
-descriptor.
-
-
-The flags and their semantics are described in
-open(2).
-
-
-__F_GETLK__, __F_SETLK__ and __F_SETLKW__ are used
-to manage discretionary file locks. The third argument
-''lock'' is a pointer to a struct flock (that may be
-overwritten by this call).
-
-
-__F_GETLK__
-
-
-Return the flock structure that prevents us from obtaining
-the lock, or set the __l_type__ field of the lock to
-__F_UNLCK__ if there is no obstruction.
-
-
-
-
-
-
-
-
-
+;__F_SETLK__:
The lock is set (when __l_type__ is __F_RDLCK__ or __F_WRLCK__) or cleared (when it is __F_UNLCK__). If the lock is held by someone else, this call returns -1 and sets ''errno'' to __EACCES__ or
__EAGAIN__.
+;__F_SETLKW__: Like __F_SETLK__, but instead of returning an error we wait for the lock to be released. If a signal that is to be caught is received while __fcntl__ is waiting, it is interrupted and (after the signal handler has returned) returns immediately (with return value -1 and ''errno'' set to __EINTR__).
-__F_SETLKW
__
+__F_GETOWN
__, __F_SETOWN__, __F_GETSIG__ and __F_SETSIG__ are used to manage I/O availability signals:
+;__F_GETOWN__: Get the process ID or process group currently receiving [SIGIO] and [SIGURG] signals for events on file descriptor ''fd''. Process groups are returned as negative values.
-Like
__F_SETLK
__, but instead of returning an error we
-wait for
the lock to be released. If a signal
that is to be
-caught is received while __fcntl__ is waiting, it is
-interrupted and (after the signal handler has returned)
-returns immediately (with return value -1
and ''errno
''
-set to
__EINTR
__).
+;
__F_SETOWN
__: Set
the process ID or process group
that will receive [SIGIO]
and [SIGURG] signals for events on file descriptor
''fd
''. Process groups are specified using negative values. (
__F
_SETSIG
__ can be used to specify a different signal instead of SIGIO
).
+;:If you set the __O_ASYNC__ status flag on a file descriptor (either by providing this flag with the open(2) call, or by using the __F_SETFL__ command of fcntl(2)), a [SIGIO] signal is sent whenever input or output becomes possible on that file descriptor.
-__F_GETOWN
__,
__F_SETOWN
__, __F_GETSIG__ and
-__F_SETSIG__
are used
to manage I/O availability
-:
+;:The process or process group to receive the signal can be selected by using the
__F_SETOWN
__ command to the
__fcntl
__ function. If the file descriptor is a socket
, this also selects the recipient of SIGURG signals that
are delivered when out-of-band data arrives on that socket. (SIGURG is sent in any situation where select(2) would report the socket as having an "exceptional condition".) If the file descriptor corresponds
to a terminal device, then [SIGIO]
signals are sent to the foreground process group of the terminal.
+;__F_GETSIG__: Get the signal sent when input or output becomes possible. A value of zero means SIGIO is sent. Any other value (including SIGIO) is the signal sent instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.
-__F_GETOWN
__
+;
__F_SETSIG
__: Sets the signal sent when input or output becomes possible. A value of zero means to send the default [SIGIO] signal. Any other value (including [SIGIO]) is the signal to send instead, and in this case additional info is available to the signal handler if installed with SA_SIGINFO.
+;:By using F_SETSIG with a non-zero value, and setting SA_SIGINFO for the signal handler (see sigaction(2)), extra information about I/O events is passed to the handler in a ''siginfo_t'' structure. If the ''si_code'' field indicates the source is SI_SIGIO, the ''si_fd'' field gives the file descriptor associated with the event. Otherwise, there is no indication which file descriptors are pending, and you should use the usual mechanisms (select(2), poll(2), read(2) with __O_NONBLOCK__ set etc.) to determine which file descriptors are available for I/O.
-Get the process ID or process group currently receiving
-SIGIO and SIGURG signals for
events on file descriptor
-''fd''
. Process groups are returned
as negative
-values
.
+;:By selecting a POSIX.1b real time signal (value >= SIGRTMIN), multiple I/O
events may be queued using the same signal numbers. (Queuing is dependent
on available memory)
. Extra information is available if SA_SIGINFO is set for the signal handler,
as above
.
+;:Using these mechanisms, a program can implement fully asynchronous I/O without using select(2) or poll(2) most of the time.
-__F_SETOWN__
+;:The use of __O_ASYNC__, __F_GETOWN__,
__F_SETOWN__ is specific to BSD and Linux. __F_GETSIG__ and __F_SETSIG__ are Linux-specific. [POSIX] has asynchronous I/O and the ''aio_sigevent'' structure to achieve similar
+things; these are also available in Linux as part of the GNU C Library (Glibc).
-
-Set the process ID or process group that will receive SIGIO
-and SIGURG signals for events on file descriptor ''fd''.
-Process groups are specified using negative values.
-(__F_SETSIG__ can be used to specify a different signal
-instead of SIGIO).
-
-
-If you set the __O_ASYNC__ status flag on a file
-descriptor (either by providing this flag with the
-open(2) call, or by using the __F_SETFL__ command
-of __fcntl__), a SIGIO signal is sent whenever input or
-output becomes possible on that file
-descriptor.
-
-
-The process or process group to receive the signal can be
-selected by using the __F_SETOWN__ command to the
-__fcntl__ function. If the file descriptor is a socket,
-this also selects the recipient of SIGURG signals that are
-delivered when out-of-band data arrives on that socket.
-(SIGURG is sent in any situation where select(2)
-would report the socket as having an
-__
-
-
-__F_GETSIG__
-
-
-Get the signal sent when input or output becomes possible. A
-value of zero means SIGIO is sent. Any other value
-(including SIGIO) is the signal sent instead, and in this
-case additional info is available to the signal handler if
-installed with SA_SIGINFO.
-
-
-__F_SETSIG__
-
-
-Sets the signal sent when input or output becomes possible.
-A value of zero means to send the default SIGIO signal. Any
-other value (including SIGIO) is the signal to send instead,
-and in this case additional info is available to the signal
-handler if installed with SA_SIGINFO.
-
-
-By using F_SETSIG with a non-zero value, and setting
-SA_SIGINFO for the signal handler (see sigaction(2)),
-extra information about I/O events is passed to the handler
-in a ''siginfo_t'' structure. If the ''si_code'' field
-indicates the source is SI_SIGIO, the ''si_fd'' field
-gives the file descriptor associated with the event.
-Otherwise, there is no indication which file descriptors are
-pending, and you should use the usual mechanisms
-(select(2), poll(2), read(2) with
-__O_NONBLOCK__ set etc.) to determine which file
-descriptors are available for I/O.
-
-
-By selecting a POSIX.1b real time signal (value
-
-
-Using these mechanisms, a program can implement fully
-asynchronous I/O without using select(2) or
-poll(2) most of the time.
-
-
-The use of __O_ASYNC__, __F_GETOWN__, __F_SETOWN__
-is specific to BSD and Linux. __F_GETSIG__ and
-__F_SETSIG__ are Linux-specific. POSIX has asynchronous
-I/O and the ''aio_sigevent'' structure to achieve similar
-things; these are also available in Linux as part of the GNU
-C Library (Glibc).
!!RETURN VALUE
+For a successful call, the return value depends on the operation:
+;__F_DUPFD__: The new descriptor.
+;__F_GETFD__: Value of flag.
+;__F_GETFL__: Value of flags.
+;__F_GETOWN__: Value of descriptor owner.
+;__F_GETSIG__: Value of signal sent when read or write becomes possible, or zero for traditional SIGIO behaviour.
+;All other commands: Zero.
-For a successful call, the return value depends on the
-operation:
-
-
-__F_DUPFD__
-
-
-The new descriptor.
-
-
-__F_GETFD__
-
-
-Value of flag.
-
-
-__F_GETFL__
-
-
-Value of flags.
-
-
-__F_GETOWN__
-
-
-Value of descriptor owner.
-
-
-__F_GETSIG__
-
-
-Value of signal sent when read or write becomes possible, or
-zero for traditional SIGIO behaviour.
-
-
-All other commands
-
-
-Zero.
-
-
-
-
+On error, -1 is returned, and ''errno'' is set appropriately.
!!ERRORS
+;[EACCES]: Operation is prohibited by locks held by other processes.
+;[EAGAIN]: Operation is prohibited because the file has been memory-mapped by another process.
+;[EBADF]: 'fd'' is not an open file descriptor or command was __F_SETLK__ or __F_SETLKW__ and file descriptor open mode doesn't match with type of lock requested (eg: file descriptor was read only and the lock requested was __F_WRLCK__).
+;[EDEADLK]: It was detected that the specified __F_SETLKW__ command would cause a deadlock.
+;[EFAULT]: ''lock'' is outside your accessible address space.
+;[EINTR]: For __F_SETLKW__, the command was interrupted by a signal. For __F_GETLK__ and __F_SETLK__, the command was interrupted by a signal before the lock was checked or acquired. Most likely when locking a remote file (e.g. locking over NFS), but can sometimes happen locally.
+;[EINVAL]: For __F_DUPFD__, ''arg'' is negative or is greater than the maximum allowable value. For __F_SETSIG__, ''arg'' is not an allowable signal number.
+;[EMFILE]: For __F_DUPFD__, the process already has the maximum number of file descriptors open.
+;[ENOLCK]: Too many segment locks open, lock table is full, or a remote locking protocol failed (e.g. locking over NFS).
+;[EPERM]: Attempted to clear the __O_APPEND__ flag on a file that has the append-only attribute set.
-__EACCES
__
+!!NOTES
+The errors returned by dup2(2) are different from those returned by
__F
_DUPFD
__.
+!!CONFORMING TO
+SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are specified in POSIX.1. F_GETOWN and F_SETOWN are BSDisms not supported in SVr4; F_GETSIG and F_SETSIG are specific to Linux. The flags legal for F_GETFL/F_SETFL are those supported by open(2) and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY, and O_RDWR are specified in POSIX.1. SVr4 supports several other options and flags not documented here.
-Operation is prohibited by locks held by other
-processes
.
+SVr4 documents additional [EIO], [ENOLINK] and [EOVERFLOW] error conditions
.
+!!EXAMPLES
+ /*
+ * This program demonstrates using fcntl(2) similar to dup(2)
+ */
-__EAGAIN__
+ #include <sys/stat.h> /* for S
_* constants */
+ #include <unistd.h> /* write(2), close(2) prototype */
+ #include <fcntl.h> /* fcntl(2), creat(2) prototypes, F
_* constants */
+ #include <stdio.h> /* fprintf(3), stderr prototype */
+ #include <string.h> /* strerror(3) prototype */
+ #include <errno.h> /* for errno prototype */
+ #define FILENAME "/tmp/fcntl_dup.example"
-Operation is prohibited because the
file has been
-memory-mapped by another process.
+ /*
+ * Input:
+ * fd: a
file descriptor to write to
+ * msg: A message to write
+ * Returns:
+ * : success
+ * non : error (error message already written to stderr)
+ */
+ int do_write(int fd,char *msg)
+ {
+ int err;
+ err=write(fd,msg,strlen(msg));
-__EBADF__
+ if (err==-1) {
+ fprintf(
+ stderr,
+ "write(fd,\"%s\",strlen(\"%s\")): %s (%i)\n",
+ msg,
+ msg,
+ strerror(errno),
+ errno);
+ return 1;
+ }
+ if (err!=strlen(msg)) {
+ fprintf(
+ stderr,
+ "write did not write the full length, and I'm too dumb to try again\n"
+ );
+ return 1;
+ }
+ return 0;
+ }
-''fd'' is not an open file descriptor or command was
-__F_SETLK__ or __F_SETLKW and__ file descriptor open
-mode doesn't match with type of lock requested (eg: file
-descriptor was read only and the lock requested was
-__F_WRLCK__).
+ int main(int argc,char **argv)
+ {
+ int fd;
+ int fd2;
+ fd=creat(FILENAME,S_IRUSR|S_IWUSR);
+ if (fd==-1) {
+ fprintf(
+ stderr,
+ "creat(\"%s\",S_IRUSR|S_IWUSR): %s (%i)\n",
+ FILENAME,
+ strerror(errno),
+ errno);
+ return 1;
+ }
-__EDEADLK__
+ if (do
_write(fd,"This is some sample text\n")!=) {
+ return 1;
+ }
+ /* Now, use fcntl to create a new fd, greater or equal to 0 */
+ fd2 = fcntl(fd,F_DUPFD,0);
-It was detected that the specified __
F_SETLKW__ command
-would cause a deadlock.
+ if (fd2 == -1) {
+ fprintf(
+ stderr,
+ "fcntl(fd,
F_DUPFD,): %s (%i)\n",
+ strerror(errno),
+ errno);
+ return 1;
+ }
+ if (do_write(fd2,"This proves that fd2 is working\n")!=0) {
+ return 1;
+ }
-__EFAULT__
+ if (do
_write(fd,"This proves that fd's file pointer has been moved by fd2 "
+ "writing to the socket\n")!=) {
+ return 1;
+ }
+ close(fd);
+ close(fd2);
+ return 0;
+ }
-''lock'' is outside your accessible address
-space.
-
-
-__EINTR__
-
-
-For __F_SETLKW__, the command was interrupted by a
-signal. For __F_GETLK__ and __F_SETLK__, the command
-was interrupted by a signal before the lock was checked or
-acquired. Most likely when locking a remote file (e.g.
-locking over NFS), but can sometimes happen
-locally.
-
-
-__EINVAL__
-
-
-For __F_DUPFD__, ''arg'' is negative or is greater
-than the maximum allowable value. For __F_SETSIG__,
-''arg'' is not an allowable signal number.
-
-
-__EMFILE__
-
-
-For __F_DUPFD__, the process already has the maximum
-number of file descriptors open.
-
-
-__ENOLCK__
-
-
-Too many segment locks open, lock table is full, or a remote
-locking protocol failed (e.g. locking over
-NFS).
-
-
-__EPERM__
-
-
-Attempted to clear the __O_APPEND__ flag on a file that
-has the append-only attribute set.
-!!NOTES
-
-
-The errors returned by __dup2__ are different from those
-returned by __F_DUPFD__.
-!!CONFORMING TO
-
-
-SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations
-F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK,
-F_SETLK and F_SETLKW are specified in POSIX.1. F_GETOWN and
-F_SETOWN are BSDisms not supported in SVr4; F_GETSIG and
-F_SETSIG are specific to Linux. The flags legal for
-F_GETFL/F_SETFL are those supported by open(2) and
-vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY,
-and O_RDWR are specified in POSIX.1. SVr4 supports several
-other options and flags not documented here.
-
-
-SVr4 documents additional EIO, ENOLINK and EOVERFLOW error
-conditions.
!!SEE ALSO
-
-
-
-
-----
+dup2(2), flock(2), open(2), socket(2)
