1 .\" Copyright (c) 1983, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
33 .\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
34 .\" $DragonFly: src/lib/libc/sys/fcntl.2,v 1.2 2003/06/17 04:26:47 dillon Exp $
47 .Fn fcntl "int fd" "int cmd" "..."
50 provides for control over descriptors.
53 is a descriptor to be operated on by
55 as described below. Depending on the value of
58 can take an additional third argument
60 .Bl -tag -width F_GETOWNX
62 Return a new descriptor as follows:
64 .Bl -bullet -compact -offset 4n
66 Lowest numbered available descriptor greater than or equal to
69 Same object references as the original descriptor.
71 New descriptor shares the same file offset if the object
74 Same access mode (read, write or read/write).
76 Same file status flags (i.e., both file descriptors
77 share the same file status flags).
79 The close-on-exec flag associated with the new file descriptor
80 is set to remain open across
85 Get the close-on-exec flag associated with the file descriptor
89 If the returned value ANDed with
92 the file will remain open across
94 otherwise the file will be closed upon execution of
99 Set the close-on-exec flag associated with
109 Get descriptor status flags, as described below
113 Set descriptor status flags to
116 Get the process ID or process group
121 signals; process groups are returned
126 Set the process or process group
132 process groups are specified by supplying
134 as negative, otherwise
136 is interpreted as a process ID.
143 flags are as follows:
144 .Bl -tag -width O_NONBLOCKX
146 Non-blocking I/O; if no data is available to a
150 operation would block,
151 the read or write call returns -1 with the error
154 Force each write to append at the end of file;
160 Minimize or eliminate the cache effects of reading and writing. The system
161 will attempt to avoid caching the data you read or write. If it cannot
162 avoid caching the data, it will minimize the impact the data has on the cache.
163 Use of this flag can drastically reduce performance if not used with care.
167 signal to be sent to the process group
168 when I/O is possible, e.g.,
169 upon availability of data to be read.
172 Several commands are available for doing advisory file locking;
173 they all operate on the following structure:
176 off_t l_start; /* starting offset */
177 off_t l_len; /* len = 0 means until end of file */
178 pid_t l_pid; /* lock owner */
179 short l_type; /* lock type: read/write, etc. */
180 short l_whence; /* type of l_start */
183 The commands available for advisory record locking are as follows:
184 .Bl -tag -width F_SETLKWX
186 Get the first lock that blocks the lock description pointed to by the
189 taken as a pointer to a
192 The information retrieved overwrites the information passed to
197 If no lock is found that would prevent this lock from being created,
198 the structure is left unchanged by this function call except for the
199 lock type which is set to
202 Set or clear a file segment lock according to the lock description
203 pointed to by the third argument,
205 taken as a pointer to a
209 is used to establish shared (or read) locks
211 or exclusive (or write) locks,
213 as well as remove either type of lock
215 If a shared or exclusive lock cannot be set,
217 returns immediately with
220 This command is the same as
222 except that if a shared or exclusive lock is blocked by other locks,
223 the process waits until the request can be satisfied.
224 If a signal that is to be caught is received while
226 is waiting for a region, the
228 will be interrupted if the signal handler has not specified the
234 When a shared lock has been set on a segment of a file,
235 other processes can set shared locks on that segment
237 A shared lock prevents any other process from setting an exclusive
238 lock on any portion of the protected area.
239 A request for a shared lock fails if the file descriptor was not
240 opened with read access.
242 An exclusive lock prevents any other process from setting a shared lock or
243 an exclusive lock on any portion of the protected area.
244 A request for an exclusive lock fails if the file was not
245 opened with write access.
254 to indicate that the relative offset,
256 bytes, will be measured from the start of the file,
257 current position, or end of the file, respectively.
260 is the number of consecutive bytes to be locked.
263 is negative, the result is undefined.
266 field is only used with
268 to return the process ID of the process holding a blocking lock.
271 request, the value of
276 Locks may start and extend beyond the current end of a file,
277 but may not start or extend before the beginning of the file.
278 A lock is set to extend to the largest possible value of the
279 file offset for that file if
286 point to the beginning of the file, and
288 is zero, the entire file is locked.
289 If an application wishes only to do entire file locking, the
291 system call is much more efficient.
293 There is at most one type of lock set for each byte in the file.
294 Before a successful return from an
298 request when the calling process has previously existing locks
299 on bytes in the region specified by the request,
300 the previous lock type for each byte in the specified
301 region is replaced by the new lock type.
302 As specified above under the descriptions
303 of shared locks and exclusive locks, an
307 request fails or blocks respectively when another process has existing
308 locks on bytes in the specified region and the type of any of those
309 locks conflicts with the type specified in the request.
311 This interface follows the completely stupid semantics of System V and
313 that require that all locks associated with a file for a given process are
316 file descriptor for that file is closed by that process.
317 This semantic means that applications must be aware of any files that
318 a subroutine library may access.
319 For example if an application for updating the password file locks the
320 password file database while making the update, and then calls
322 to retrieve a record,
323 the lock will be lost because
325 opens, reads, and closes the password database.
326 The database close will release all locks that the process has
327 associated with the database, even if the library routine never
328 requested a lock on the database.
329 Another minor semantic problem with this interface is that
330 locks are not inherited by a child process created using the
335 interface has much more rational last close semantics and
336 allows locks to be inherited by child processes.
338 is recommended for applications that want to ensure the integrity
339 of their locks when using library routines or wish to pass locks
345 locks may be safely used concurrently but
349 if the process holding a blocking lock previously locked the
353 All locks associated with a file for a given process are
354 removed when the process terminates.
356 All locks obtained before a call to
358 remain in effect until the new program releases them.
359 If the new program does not know about the locks, they will not be
360 released until the program exits.
362 A potential for deadlock occurs if a process controlling a locked region
363 is put to sleep by attempting to lock the locked region of another process.
364 This implementation detects that sleeping until a locked region is unlocked
365 would cause a deadlock and fails with an
369 Upon successful completion, the value returned depends on
372 .Bl -tag -width F_GETOWNX -offset indent
374 A new file descriptor.
376 Value of flag (only the low-order bit is defined).
380 Value of file descriptor owner.
385 Otherwise, a value of -1 is returned and
387 is set to indicate the error.
403 and the segment of a file to be locked is already
404 exclusive-locked by another process;
405 or the type is an exclusive lock and some portion of the
406 segment of a file to be locked is already shared-locked or
407 exclusive-locked by another process.
410 is not a valid open file descriptor.
424 is not a valid file descriptor open for reading.
438 is not a valid file descriptor open for writing.
444 and a deadlock condition was detected.
450 and the function was interrupted by a signal.
457 is negative or greater than the maximum allowable number
459 .Xr getdtablesize 2 ) .
468 and the data to which
470 points is not valid, or
472 refers to a file that does not support locking.
478 and the maximum number of file descriptors permitted for the
479 process are already in use,
480 or no file descriptors greater than or equal to
490 and satisfying the lock or unlock request would result in the
491 number of locked regions in the system exceeding a system-imposed limit.
497 the process ID or process group given as an argument is in a
498 different session than the caller.
504 the process ID given as argument is not in use.
509 refers to a descriptor open on a terminal device (as opposed to a
510 descriptor open on a socket), a
514 can fail for the same reasons as in
520 for the reasons as stated in
526 .Xr getdtablesize 2 ,
534 function call appeared in