1FCNTL(3P) POSIX Programmer's Manual FCNTL(3P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 fcntl - file control
13
15 #include <unistd.h>
16 #include <fcntl.h>
17 int fcntl(int fildes, int cmd, ...);
19
22 The fcntl() function shall perform the operations described below on
23 open files. The fildes argument is a file descriptor.
24 The available values for cmd are defined in <fcntl.h> and are as fol‐
26 lows:
27 F_DUPFD
29 Return a new file descriptor which shall be the lowest numbered
30 available (that is, not already open) file descriptor greater
31 than or equal to the third argument, arg, taken as an integer of
32 type int. The new file descriptor shall refer to the same open
33 file description as the original file descriptor, and shall
34 share any locks. The FD_CLOEXEC flag associated with the new
35 file descriptor shall be cleared to keep the file open across
36 calls to one of the exec functions.
37 F_GETFD
39 Get the file descriptor flags defined in <fcntl.h> that are
40 associated with the file descriptor fildes. File descriptor
41 flags are associated with a single file descriptor and do not
42 affect other file descriptors that refer to the same file.
43 F_SETFD
45 Set the file descriptor flags defined in <fcntl.h>, that are
46 associated with fildes, to the third argument, arg, taken as
47 type int. If the FD_CLOEXEC flag in the third argument is 0, the
48 file shall remain open across the exec functions; otherwise, the
49 file shall be closed upon successful execution of one of the
50 exec functions.
51 F_GETFL
53 Get the file status flags and file access modes, defined in
54 <fcntl.h>, for the file description associated with fildes. The
55 file access modes can be extracted from the return value using
56 the mask O_ACCMODE, which is defined in <fcntl.h>. File status
57 flags and file access modes are associated with the file
58 description and do not affect other file descriptors that refer
59 to the same file with different open file descriptions.
60 F_SETFL
62 Set the file status flags, defined in <fcntl.h>, for the file
63 description associated with fildes from the corresponding bits
64 in the third argument, arg, taken as type int. Bits correspond‐
65 ing to the file access mode and the file creation flags, as
66 defined in <fcntl.h>, that are set in arg shall be ignored. If
67 any bits in arg other than those mentioned here are changed by
68 the application, the result is unspecified.
69 F_GETOWN
71 If fildes refers to a socket, get the process or process group
72 ID specified to receive SIGURG signals when out-of-band data is
73 available. Positive values indicate a process ID; negative val‐
74 ues, other than -1, indicate a process group ID. If fildes does
75 not refer to a socket, the results are unspecified.
76 F_SETOWN
78 If fildes refers to a socket, set the process or process group
79 ID specified to receive SIGURG signals when out-of-band data is
80 available, using the value of the third argument, arg, taken as
81 type int. Positive values indicate a process ID; negative val‐
82 ues, other than -1, indicate a process group ID. If fildes does
83 not refer to a socket, the results are unspecified.
84 The following values for cmd are available for advisory record locking.
87 Record locking shall be supported for regular files, and may be sup‐
88 ported for other files.
89 F_GETLK
91 Get the first lock which blocks the lock description pointed to
92 by the third argument, arg, taken as a pointer to type struct
93 flock, defined in <fcntl.h>. The information retrieved shall
94 overwrite the information passed to fcntl() in the structure
95 flock. If no lock is found that would prevent this lock from
96 being created, then the structure shall be left unchanged except
97 for the lock type which shall be set to F_UNLCK.
98 F_SETLK
100 Set or clear a file segment lock according to the lock descrip‐
101 tion pointed to by the third argument, arg, taken as a pointer
102 to type struct flock, defined in <fcntl.h>. F_SETLK can estab‐
103 lish shared (or read) locks (F_RDLCK) or exclusive (or write)
104 locks (F_WRLCK), as well as to remove either type of lock
105 (F_UNLCK). F_RDLCK, F_WRLCK, and F_UNLCK are defined in
106 <fcntl.h>. If a shared or exclusive lock cannot be set, fcntl()
107 shall return immediately with a return value of -1.
108 F_SETLKW
110 This command shall be equivalent to F_SETLK except that if a
111 shared or exclusive lock is blocked by other locks, the thread
112 shall wait until the request can be satisfied. If a signal that
113 is to be caught is received while fcntl() is waiting for a
114 region, fcntl() shall be interrupted. Upon return from the sig‐
115 nal handler, fcntl() shall return -1 with errno set to [EINTR],
116 and the lock operation shall not be done.
117 Additional implementation-defined values for cmd may be defined in
120 <fcntl.h>. Their names shall start with F_.
121 When a shared lock is set on a segment of a file, other processes shall
123 be able to set shared locks on that segment or a portion of it. A
124 shared lock prevents any other process from setting an exclusive lock
125 on any portion of the protected area. A request for a shared lock shall
126 fail if the file descriptor was not opened with read access.
127 An exclusive lock shall prevent any other process from setting a shared
129 lock or an exclusive lock on any portion of the protected area. A
130 request for an exclusive lock shall fail if the file descriptor was not
131 opened with write access.
132 The structure flock describes the type ( l_type), starting offset (
134 l_whence), relative offset ( l_start), size ( l_len), and process ID (
135 l_pid) of the segment of the file to be affected.
136 The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END, to indicate
138 that the relative offset l_start bytes shall be measured from the start
139 of the file, current position, or end of the file, respectively. The
140 value of l_len is the number of consecutive bytes to be locked. The
141 value of l_len may be negative (where the definition of off_t permits
142 negative values of l_len). The l_pid field is only used with F_GETLK to
143 return the process ID of the process holding a blocking lock. After a
144 successful F_GETLK request, when a blocking lock is found, the values
145 returned in the flock structure shall be as follows:
146 l_type Type of blocking lock found.
148 l_whence
150 SEEK_SET.
151 l_start
153 Start of the blocking lock.
154 l_len Length of the blocking lock.
156 l_pid Process ID of the process that holds the blocking lock.
158 If the command is F_SETLKW and the process must wait for another
161 process to release a lock, then the range of bytes to be locked shall
162 be determined before the fcntl() function blocks. If the file size or
163 file descriptor seek offset change while fcntl() is blocked, this shall
164 not affect the range of bytes locked.
165 If l_len is positive, the area affected shall start at l_start and end
167 at l_start+ l_len-1. If l_len is negative, the area affected shall
168 start at l_start+ l_len and end at l_start-1. Locks may start and
169 extend beyond the current end of a file, but shall not extend before
170 the beginning of the file. A lock shall be set to extend to the largest
171 possible value of the file offset for that file by setting l_len to 0.
172 If such a lock also has l_start set to 0 and l_whence is set to
173 SEEK_SET, the whole file shall be locked.
174 There shall be at most one type of lock set for each byte in the file.
176 Before a successful return from an F_SETLK or an F_SETLKW request when
177 the calling process has previously existing locks on bytes in the
178 region specified by the request, the previous lock type for each byte
179 in the specified region shall be replaced by the new lock type. As
180 specified above under the descriptions of shared locks and exclusive
181 locks, an F_SETLK or an F_SETLKW request (respectively) shall fail or
182 block when another process has existing locks on bytes in the specified
183 region and the type of any of those locks conflicts with the type spec‐
184 ified in the request.
185 All locks associated with a file for a given process shall be removed
187 when a file descriptor for that file is closed by that process or the
188 process holding that file descriptor terminates. Locks are not inher‐
189 ited by a child process.
190 A potential for deadlock occurs if a process controlling a locked
192 region is put to sleep by attempting to lock another process' locked
193 region. If the system detects that sleeping until a locked region is
194 unlocked would cause a deadlock, fcntl() shall fail with an [EDEADLK]
195 error.
196 An unlock (F_UNLCK) request in which l_len is non-zero and the offset
198 of the last byte of the requested segment is the maximum value for an
199 object of type off_t, when the process has an existing lock in which
200 l_len is 0 and which includes the last byte of the requested segment,
201 shall be treated as a request to unlock from the start of the requested
202 segment with an l_len equal to 0. Otherwise, an unlock (F_UNLCK)
203 request shall attempt to unlock only the requested segment.
204 When the file descriptor fildes refers to a shared memory object, the
206 behavior of fcntl() shall be the same as for a regular file except the
207 effect of the following values for the argument cmd shall be unspeci‐
208 fied: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW.
209 If fildes refers to a typed memory object, the result of the fcntl()
211 function is unspecified.
212
214 Upon successful completion, the value returned shall depend on cmd as
215 follows:
216 F_DUPFD
218 A new file descriptor.
219 F_GETFD
221 Value of flags defined in <fcntl.h>. The return value shall not
222 be negative.
223 F_SETFD
225 Value other than -1.
226 F_GETFL
228 Value of file status flags and access modes. The return value is
229 not negative.
230 F_SETFL
232 Value other than -1.
233 F_GETLK
235 Value other than -1.
236 F_SETLK
238 Value other than -1.
239 F_SETLKW
241 Value other than -1.
242 F_GETOWN
244 Value of the socket owner process or process group; this will
245 not be -1.
246 F_SETOWN
248 Value other than -1.
249 Otherwise, -1 shall be returned and errno set to indicate the error.
252
254 The fcntl() function shall fail if:
255 EACCES or EAGAIN
257 The cmd argument is F_SETLK; the type of lock ( l_type) is a
259 shared (F_RDLCK) or exclusive (F_WRLCK) lock and the segment of
260 a file to be locked is already exclusive-locked by another
261 process, or the type is an exclusive lock and some portion of
262 the segment of a file to be locked is already shared-locked or
263 exclusive-locked by another process.
264 EBADF The fildes argument is not a valid open file descriptor, or the
266 argument cmd is F_SETLK or F_SETLKW, the type of lock, l_type,
267 is a shared lock (F_RDLCK), and fildes is not a valid file
268 descriptor open for reading, or the type of lock, l_type, is an
269 exclusive lock (F_WRLCK), and fildes is not a valid file
270 descriptor open for writing.
271 EINTR The cmd argument is F_SETLKW and the function was interrupted by
273 a signal.
274 EINVAL The cmd argument is invalid, or the cmd argument is F_DUPFD and
276 arg is negative or greater than or equal to {OPEN_MAX}, or the
277 cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the data
278 pointed to by arg is not valid, or fildes refers to a file that
279 does not support locking.
280 EMFILE The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors are
282 currently open in the calling process, or no file descriptors
283 greater than or equal to arg are available.
284 ENOLCK The argument cmd is F_SETLK or F_SETLKW and satisfying the lock
286 or unlock request would result in the number of locked regions
287 in the system exceeding a system-imposed limit.
288 EOVERFLOW
290 One of the values to be returned cannot be represented cor‐
291 rectly.
292 EOVERFLOW
294 The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the small‐
295 est or, if l_len is non-zero, the largest offset of any byte in
296 the requested segment cannot be represented correctly in an
297 object of type off_t.
298 The fcntl() function may fail if:
301 EDEADLK
303 The cmd argument is F_SETLKW, the lock is blocked by a lock from
304 another process, and putting the calling process to sleep to
305 wait for that lock to become free would cause a deadlock.
306 The following sections are informative.
309
311 None.
312
314 None.
315
317 The ellipsis in the SYNOPSIS is the syntax specified by the ISO C stan‐
318 dard for a variable number of arguments. It is used because System V
319 uses pointers for the implementation of file locking functions.
320 The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent
322 flag values to allow for future growth. Applications using these func‐
323 tions should do a read-modify-write operation on them, rather than
324 assuming that only the values defined by this volume of
325 IEEE Std 1003.1-2001 are valid. It is a common error to forget this,
326 particularly in the case of F_SETFD.
327 This volume of IEEE Std 1003.1-2001 permits concurrent read and write
329 access to file data using the fcntl() function; this is a change from
330 the 1984 /usr/group standard and early proposals. Without concurrency
331 controls, this feature may not be fully utilized without occasional
332 loss of data.
333 Data losses occur in several ways. One case occurs when several pro‐
335 cesses try to update the same record, without sequencing controls; sev‐
336 eral updates may occur in parallel and the last writer "wins". Another
337 case is a bit-tree or other internal list-based database that is under‐
338 going reorganization. Without exclusive use to the tree segment by the
339 updating process, other reading processes chance getting lost in the
340 database when the index blocks are split, condensed, inserted, or
341 deleted. While fcntl() is useful for many applications, it is not
342 intended to be overly general and does not handle the bit-tree example
343 well.
344 This facility is only required for regular files because it is not
346 appropriate for many devices such as terminals and network connections.
347 Since fcntl() works with "any file descriptor associated with that
349 file, however it is obtained", the file descriptor may have been inher‐
350 ited through a fork() or exec operation and thus may affect a file that
351 another process also has open.
352 The use of the open file description to identify what to lock requires
354 extra calls and presents problems if several processes are sharing an
355 open file description, but there are too many implementations of the
356 existing mechanism for this volume of IEEE Std 1003.1-2001 to use dif‐
357 ferent specifications.
358 Another consequence of this model is that closing any file descriptor
360 for a given file (whether or not it is the same open file description
361 that created the lock) causes the locks on that file to be relinquished
362 for that process. Equivalently, any close for any file/process pair
363 relinquishes the locks owned on that file for that process. But note
364 that while an open file description may be shared through fork(), locks
365 are not inherited through fork(). Yet locks may be inherited through
366 one of the exec functions.
367 The identification of a machine in a network environment is outside the
369 scope of this volume of IEEE Std 1003.1-2001. Thus, an l_sysid member,
370 such as found in System V, is not included in the locking structure.
371 Changing of lock types can result in a previously locked region being
373 split into smaller regions.
374 Mandatory locking was a major feature of the 1984 /usr/group standard.
376 For advisory file record locking to be effective, all processes that
378 have access to a file must cooperate and use the advisory mechanism
379 before doing I/O on the file. Enforcement-mode record locking is impor‐
380 tant when it cannot be assumed that all processes are cooperating. For
381 example, if one user uses an editor to update a file at the same time
382 that a second user executes another process that updates the same file
383 and if only one of the two processes is using advisory locking, the
384 processes are not cooperating. Enforcement-mode record locking would
385 protect against accidental collisions.
386 Secondly, advisory record locking requires a process using locking to
388 bracket each I/O operation with lock (or test) and unlock operations.
389 With enforcement-mode file and record locking, a process can lock the
390 file once and unlock when all I/O operations have been completed.
391 Enforcement-mode record locking provides a base that can be enhanced;
392 for example, with sharable locks. That is, the mechanism could be
393 enhanced to allow a process to lock a file so other processes could
394 read it, but none of them could write it.
395 Mandatory locks were omitted for several reasons:
397 1. Mandatory lock setting was done by multiplexing the set-group-ID
399 bit in most implementations; this was confusing, at best.
400 2. The relationship to file truncation as supported in 4.2 BSD was not
402 well specified.
403 3. Any publicly readable file could be locked by anyone. Many histori‐
405 cal implementations keep the password database in a publicly read‐
406 able file. A malicious user could thus prohibit logins. Another
407 possibility would be to hold open a long-distance telephone line.
408 4. Some demand-paged historical implementations offer memory mapped
410 files, and enforcement cannot be done on that type of file.
411 Since sleeping on a region is interrupted with any signal, alarm() may
413 be used to provide a timeout facility in applications requiring it.
414 This is useful in deadlock detection. Since implementation of full
415 deadlock detection is not always feasible, the [EDEADLK] error was made
416 optional.
417
419 None.
420
422 alarm(), close(), exec(), open(), sigaction(), the Base Definitions
423 volume of IEEE Std 1003.1-2001, <fcntl.h>, <signal.h>, <unistd.h>
424
426 Portions of this text are reprinted and reproduced in electronic form
427 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
428 -- Portable Operating System Interface (POSIX), The Open Group Base
429 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
430 Electrical and Electronics Engineers, Inc and The Open Group. In the
431 event of any discrepancy between this version and the original IEEE and
432 The Open Group Standard, the original IEEE and The Open Group Standard
433 is the referee document. The original Standard can be obtained online
434 at http://www.opengroup.org/unix/online.html .
435IEEE/The Open Group 2003 FCNTL(3P)