View Source: fcntl(2) - Waikato Linux Users Group

Edit PageHistory Diff Info LikePages
!!NAME
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''__);__

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

;: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.

;: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.

;__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_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.

;__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.

;: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_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 >=  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.

;: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.

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.

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

SVr4 documents additional [EIO], [ENOLINK] and [EOVERFLOW] error conditions.

!!EXAMPLES
 /*
  * This program demonstrates using fcntl(2) similar to dup(2)
  */

 #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"

 /*
  * Input:
  *  fd: a file descriptor to write to
  *  msg: A message to write
  * Returns:
  *  0: success
  *  non 0: error (error message already written to stderr)
  */
 int do_write(int fd,char *msg)
 {
   int err;

   err=write(fd,msg,strlen(msg));

   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;
 }

 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;
   }

   if (do_write(fd,"This is some sample text\n")!=0) {
     return 1;
   }

   /* Now, use fcntl to create a new fd, greater or equal to 0 */
   fd2 = fcntl(fd,F_DUPFD,0);

   if (fd2 == -1) {
     fprintf(
 	stderr,
 	"fcntl(fd,F_DUPFD,0): %s (%i)\n",
 	strerror(errno),
 	errno);
     return 1;
   }

   if (do_write(fd2,"This proves that fd2 is working\n")!=0) {
     return 1;
   }

   if (do_write(fd,"This proves that fd's file pointer has been moved by fd2 "
 	"writing to the socket\n")!=0) {
     return 1;
   }

   close(fd);
   close(fd2);
   return 0;
 }

!!SEE ALSO
dup2(2), flock(2), open(2), socket(2)
36 pages link to fcntl(2):
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.
Last edited on Sunday, November 3, 2002 3:12:33 pm by PerryLorier
Edit PageHistory Diff Info LikePages