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 .\" 4. Neither the name of the University nor the names of its contributors
13 .\" may be used to endorse or promote products derived from this software
14 .\" without specific prior written permission.
16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" @(#)fcntl.2 8.2 (Berkeley) 1/12/94
31 .Dd September 28, 2009
42 .Fn fcntl "int fd" "int cmd" "..."
46 system call provides for control over descriptors.
49 is a descriptor to be operated on by
52 Depending on the value of
55 can take an additional third argument
57 .Bl -tag -width F_GETOWNX
59 Return a new descriptor as follows:
61 .Bl -bullet -compact -offset 4n
63 Lowest numbered available descriptor greater than or equal to
66 Same object references as the original descriptor.
68 New descriptor shares the same file offset if the object
71 Same access mode (read, write or read/write).
73 Same file status flags (i.e., both file descriptors
74 share the same file status flags).
76 The close-on-exec flag associated with the new file descriptor
77 is set to remain open across
82 It is functionally equivalent to
83 .Bd -literal -offset indent
89 constant is not portable, so it should not be used if portability is needed.
94 Get the close-on-exec flag associated with the file descriptor
98 If the returned value ANDed with
101 the file will remain open across
103 otherwise the file will be closed upon execution of
108 Set the close-on-exec flag associated with
118 Get descriptor status flags, as described below
122 Set descriptor status flags to
125 Get the process ID or process group
130 signals; process groups are returned
135 Set the process or process group
141 process groups are specified by supplying
143 as negative, otherwise
145 is interpreted as a process ID.
152 flags are as follows:
153 .Bl -tag -width O_NONBLOCKX
155 Non-blocking I/O; if no data is available to a
159 operation would block,
160 the read or write call returns -1 with the error
163 Force each write to append at the end of file;
169 Minimize or eliminate the cache effects of reading and writing.
171 will attempt to avoid caching the data you read or write.
173 avoid caching the data, it will minimize the impact the data has on the cache.
174 Use of this flag can drastically reduce performance if not used with care.
178 signal to be sent to the process group
179 when I/O is possible, e.g.,
180 upon availability of data to be read.
183 Several commands are available for doing advisory file locking;
184 they all operate on the following structure:
187 off_t l_start; /* starting offset */
188 off_t l_len; /* len = 0 means until end of file */
189 pid_t l_pid; /* lock owner */
190 short l_type; /* lock type: read/write, etc. */
191 short l_whence; /* type of l_start */
192 int l_sysid; /* remote system id or zero for local */
195 The commands available for advisory record locking are as follows:
196 .Bl -tag -width F_SETLKWX
198 Get the first lock that blocks the lock description pointed to by the
201 taken as a pointer to a
204 The information retrieved overwrites the information passed to
209 If no lock is found that would prevent this lock from being created,
210 the structure is left unchanged by this system call except for the
211 lock type which is set to
214 Set or clear a file segment lock according to the lock description
215 pointed to by the third argument,
217 taken as a pointer to a
221 is used to establish shared (or read) locks
223 or exclusive (or write) locks,
225 as well as remove either type of lock
227 If a shared or exclusive lock cannot be set,
229 returns immediately with
232 This command is the same as
234 except that if a shared or exclusive lock is blocked by other locks,
235 the process waits until the request can be satisfied.
236 If a signal that is to be caught is received while
238 is waiting for a region, the
240 will be interrupted if the signal handler has not specified the
245 Set or clear the read ahead amount for sequential access to the third
248 which is rounded up to the nearest block size.
251 turns off read ahead.
253 Equivalent to Darwin counterpart which sets read ahead amount of 128KB
254 when the third argument,
259 turns off read ahead.
262 When a shared lock has been set on a segment of a file,
263 other processes can set shared locks on that segment
265 A shared lock prevents any other process from setting an exclusive
266 lock on any portion of the protected area.
267 A request for a shared lock fails if the file descriptor was not
268 opened with read access.
270 An exclusive lock prevents any other process from setting a shared lock or
271 an exclusive lock on any portion of the protected area.
272 A request for an exclusive lock fails if the file was not
273 opened with write access.
282 to indicate that the relative offset,
284 bytes, will be measured from the start of the file,
285 current position, or end of the file, respectively.
288 is the number of consecutive bytes to be locked.
293 means end edge of the region.
298 fields are only used with
300 to return the process ID of the process holding a blocking lock and
301 the system ID of the system that owns that process.
302 Locks created by the local system will have a system ID of zero.
305 request, the value of
310 Locks may start and extend beyond the current end of a file,
311 but may not start or extend before the beginning of the file.
312 A lock is set to extend to the largest possible value of the
313 file offset for that file if
320 point to the beginning of the file, and
322 is zero, the entire file is locked.
323 If an application wishes only to do entire file locking, the
325 system call is much more efficient.
327 There is at most one type of lock set for each byte in the file.
328 Before a successful return from an
332 request when the calling process has previously existing locks
333 on bytes in the region specified by the request,
334 the previous lock type for each byte in the specified
335 region is replaced by the new lock type.
336 As specified above under the descriptions
337 of shared locks and exclusive locks, an
341 request fails or blocks respectively when another process has existing
342 locks on bytes in the specified region and the type of any of those
343 locks conflicts with the type specified in the request.
345 This interface follows the completely stupid semantics of System V and
347 that require that all locks associated with a file for a given process are
350 file descriptor for that file is closed by that process.
351 This semantic means that applications must be aware of any files that
352 a subroutine library may access.
353 For example if an application for updating the password file locks the
354 password file database while making the update, and then calls
356 to retrieve a record,
357 the lock will be lost because
359 opens, reads, and closes the password database.
360 The database close will release all locks that the process has
361 associated with the database, even if the library routine never
362 requested a lock on the database.
363 Another minor semantic problem with this interface is that
364 locks are not inherited by a child process created using the
369 interface has much more rational last close semantics and
370 allows locks to be inherited by child processes.
373 system call is recommended for applications that want to ensure the integrity
374 of their locks when using library routines or wish to pass locks
382 locks are compatible.
383 Processes using different locking interfaces can cooperate
384 over the same file safely.
385 However, only one of such interfaces should be used within
387 If a file is locked by a process through
389 any record within the file will be seen as locked
390 from the viewpoint of another process using
399 if the process holding a blocking lock previously locked the
403 All locks associated with a file for a given process are
404 removed when the process terminates.
406 All locks obtained before a call to
408 remain in effect until the new program releases them.
409 If the new program does not know about the locks, they will not be
410 released until the program exits.
412 A potential for deadlock occurs if a process controlling a locked region
413 is put to sleep by attempting to lock the locked region of another process.
414 This implementation detects that sleeping until a locked region is unlocked
415 would cause a deadlock and fails with an
419 Upon successful completion, the value returned depends on
422 .Bl -tag -width F_GETOWNX -offset indent
424 A new file descriptor.
426 A file descriptor equal to
429 Value of flag (only the low-order bit is defined).
433 Value of file descriptor owner.
438 Otherwise, a value of -1 is returned and
440 is set to indicate the error.
444 system call will fail if:
457 and the segment of a file to be locked is already
458 exclusive-locked by another process;
459 or the type is an exclusive lock and some portion of the
460 segment of a file to be locked is already shared-locked or
461 exclusive-locked by another process.
466 is not a valid open file descriptor.
474 is not a valid file descriptor.
488 is not a valid file descriptor open for reading.
502 is not a valid file descriptor open for writing.
508 and a deadlock condition was detected.
514 and the system call was interrupted by a signal.
523 is negative or greater than the maximum allowable number
525 .Xr getdtablesize 2 ) .
534 and the data to which
544 and the maximum number of file descriptors permitted for the
545 process are already in use,
546 or no file descriptors greater than or equal to
556 and satisfying the lock or unlock request would result in the
557 number of locked regions in the system exceeding a system-imposed limit.
568 refers to a file for which locking is not supported.
579 calculation overflowed.
587 the process ID or process group given as an argument is in a
588 different session than the caller.
596 the process ID given as argument is not in use.
601 refers to a descriptor open on a terminal device (as opposed to a
602 descriptor open on a socket), a
606 can fail for the same reasons as in
612 for the reasons as stated in
619 .Xr getdtablesize 2 ,
628 constant is non portable.
629 It is provided for compatibility with AIX and Solaris.
633 system call appeared in
638 constant first appeared in