Penguin
Recent Changes
Annotated edit history of fcntl(2) version 4, including all changes. View license author blame.
Rev Author # Line
1 perry 1 !!NAME
3 PerryLorier 2 fcntl - manipulate file descriptor
1 perry 3
4 !!SYNOPSIS
3 PerryLorier 5 __#include <unistd.h>__
6 __#include <fcntl.h>__ /* for fcntl(2) prototype */
7 __int fcntl(int__ ''fd''__, int__ ''cmd''__);__
8 __int fcntl(int__ ''fd''__, int__ ''cmd''__, long__ ''arg''__);__
9 __int fcntl(int__ ''fd''__, int__ ''cmd''__, struct flock *__''lock''__);__
1 perry 10
11 !!DESCRIPTION
3 PerryLorier 12 fcntl(2) performs one of various miscellaneous operations on ''fd''. The operation in question is determined by ''cmd'':
1 perry 13
3 PerryLorier 14 ;__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.
1 perry 15
3 PerryLorier 16 ;: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.
1 perry 17
3 PerryLorier 18 ;: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.
1 perry 19
3 PerryLorier 20 ;:On success, the new descriptor is returned.
1 perry 21
3 PerryLorier 22 ;__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.
1 perry 23
3 PerryLorier 24 ;__F_SETFD__: Set the close-on-exec flag to the value specified by the __FD_CLOEXEC__ bit of ''arg''.
1 perry 25
3 PerryLorier 26 ;__F_GETFL__: Read the descriptor's flags (all flags (as set by open(2)) are returned).
1 perry 27
3 PerryLorier 28 ;__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.
1 perry 29
3 PerryLorier 30 ;:The flags are shared between copies (made with dup(2), fork(2), etc.) of the same file descriptor.
1 perry 31
3 PerryLorier 32 ;:The flags and their semantics are described in open(2).
1 perry 33
3 PerryLorier 34 __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).
1 perry 35
3 PerryLorier 36 ;__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.
1 perry 37
3 PerryLorier 38 ;__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
1 perry 39 __EAGAIN__.
40
3 PerryLorier 41 ;__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__).
1 perry 42
3 PerryLorier 43 __F_GETOWN__, __F_SETOWN__, __F_GETSIG__ and __F_SETSIG__ are used to manage I/O availability signals:
1 perry 44
3 PerryLorier 45 ;__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.
1 perry 46
3 PerryLorier 47 ;__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).
1 perry 48
3 PerryLorier 49 ;: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.
1 perry 50
3 PerryLorier 51 ;: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.
1 perry 52
3 PerryLorier 53 ;__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.
1 perry 54
3 PerryLorier 55 ;__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.
1 perry 56
3 PerryLorier 57 ;: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.
1 perry 58
3 PerryLorier 59 ;: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.
1 perry 60
3 PerryLorier 61 ;:Using these mechanisms, a program can implement fully asynchronous I/O without using select(2) or poll(2) most of the time.
1 perry 62
3 PerryLorier 63 ;: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
64 things; these are also available in Linux as part of the GNU C Library (Glibc).
1 perry 65
66 !!RETURN VALUE
3 PerryLorier 67 For a successful call, the return value depends on the operation:
1 perry 68
3 PerryLorier 69 ;__F_DUPFD__: The new descriptor.
70 ;__F_GETFD__: Value of flag.
71 ;__F_GETFL__: Value of flags.
72 ;__F_GETOWN__: Value of descriptor owner.
73 ;__F_GETSIG__: Value of signal sent when read or write becomes possible, or zero for traditional SIGIO behaviour.
74 ;All other commands: Zero.
1 perry 75
3 PerryLorier 76 On error, -1 is returned, and ''errno'' is set appropriately.
1 perry 77 !!ERRORS
78
3 PerryLorier 79 ;[EACCES]: Operation is prohibited by locks held by other processes.
80 ;[EAGAIN]: Operation is prohibited because the file has been memory-mapped by another process.
81 ;[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__).
82 ;[EDEADLK]: It was detected that the specified __F_SETLKW__ command would cause a deadlock.
83 ;[EFAULT]: ''lock'' is outside your accessible address space.
84 ;[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.
85 ;[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.
86 ;[EMFILE]: For __F_DUPFD__, the process already has the maximum number of file descriptors open.
87 ;[ENOLCK]: Too many segment locks open, lock table is full, or a remote locking protocol failed (e.g. locking over NFS).
88 ;[EPERM]: Attempted to clear the __O_APPEND__ flag on a file that has the append-only attribute set.
1 perry 89
90 !!NOTES
3 PerryLorier 91 The errors returned by dup2(2) are different from those returned by __F_DUPFD__.
1 perry 92
93 !!CONFORMING TO
3 PerryLorier 94 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.
1 perry 95
3 PerryLorier 96 SVr4 documents additional [EIO], [ENOLINK] and [EOVERFLOW] error conditions.
4 PerryLorier 97
98 !!EXAMPLES
99 /*
100 * This program demonstrates using fcntl(2) similar to dup(2)
101 */
102
103 #include <sys/stat.h> /* for S_* constants */
104 #include <unistd.h> /* write(2), close(2) prototype */
105 #include <fcntl.h> /* fcntl(2), creat(2) prototypes, F_* constants */
106 #include <stdio.h> /* fprintf(3), stderr prototype */
107 #include <string.h> /* strerror(3) prototype */
108 #include <errno.h> /* for errno prototype */
109
110 #define FILENAME "/tmp/fcntl_dup.example"
111
112 /*
113 * Input:
114 * fd: a file descriptor to write to
115 * msg: A message to write
116 * Returns:
117 * 0: success
118 * non 0: error (error message already written to stderr)
119 */
120 int do_write(int fd,char *msg)
121 {
122 int err;
123
124 err=write(fd,msg,strlen(msg));
125
126 if (err==-1) {
127 fprintf(
128 stderr,
129 "write(fd,\"%s\",strlen(\"%s\")): %s (%i)\n",
130 msg,
131 msg,
132 strerror(errno),
133 errno);
134 return 1;
135 }
136
137 if (err!=strlen(msg)) {
138 fprintf(
139 stderr,
140 "write did not write the full length, and I'm too dumb to try again\n"
141 );
142 return 1;
143 }
144 return 0;
145 }
146
147 int main(int argc,char **argv)
148 {
149 int fd;
150 int fd2;
151
152 fd=creat(FILENAME,S_IRUSR|S_IWUSR);
153 if (fd==-1) {
154 fprintf(
155 stderr,
156 "creat(\"%s\",S_IRUSR|S_IWUSR): %s (%i)\n",
157 FILENAME,
158 strerror(errno),
159 errno);
160 return 1;
161 }
162
163 if (do_write(fd,"This is some sample text\n")!=0) {
164 return 1;
165 }
166
167 /* Now, use fcntl to create a new fd, greater or equal to 0 */
168 fd2 = fcntl(fd,F_DUPFD,0);
169
170 if (fd2 == -1) {
171 fprintf(
172 stderr,
173 "fcntl(fd,F_DUPFD,0): %s (%i)\n",
174 strerror(errno),
175 errno);
176 return 1;
177 }
178
179 if (do_write(fd2,"This proves that fd2 is working\n")!=0) {
180 return 1;
181 }
182
183 if (do_write(fd,"This proves that fd's file pointer has been moved by fd2 "
184 "writing to the socket\n")!=0) {
185 return 1;
186 }
187
188 close(fd);
189 close(fd2);
190 return 0;
191 }
1 perry 192
193 !!SEE ALSO
3 PerryLorier 194 dup2(2), flock(2), open(2), socket(2)
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.

PHP Warning

lib/blame.php:177: Warning: Invalid argument supplied for foreach() (...repeated 7 times)