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