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
29 .\" $FreeBSD: src/lib/libc/sys/fcntl.2,v 1.16.2.13 2002/07/22 15:15:16 bde Exp $
42 .Fn fcntl "int fd" "int cmd" "..."
45 provides for control over descriptors.
48 is a descriptor to be operated on by
50 as described below. Depending on the value of
53 can take an additional third argument
55 .Bl -tag -width F_GETOWNX
57 Return a new descriptor as follows:
59 .Bl -bullet -compact -offset 4n
61 Lowest numbered available descriptor greater than or equal to
64 Same object references as the original descriptor.
66 New descriptor shares the same file offset if the object
69 Same access mode (read, write or read/write).
71 Same file status flags (i.e., both file descriptors
72 share the same file status flags).
74 The close-on-exec flag associated with the new file descriptor
75 is set to remain open across
80 Get the close-on-exec flag associated with the file descriptor
84 If the returned value ANDed with
87 the file will remain open across
89 otherwise the file will be closed upon execution of
94 Set the close-on-exec flag associated with
104 Get descriptor status flags, as described below
108 Set descriptor status flags to
111 Get the process ID or process group
116 signals; process groups are returned
121 Set the process or process group
127 process groups are specified by supplying
129 as negative, otherwise
131 is interpreted as a process ID.
138 flags are as follows:
139 .Bl -tag -width O_NONBLOCKX
141 Non-blocking I/O; if no data is available to a
145 operation would block,
146 the read or write call returns -1 with the error
149 Force each write to append at the end of file;
155 Minimize or eliminate the cache effects of reading and writing. The system
156 will attempt to avoid caching the data you read or write. If it cannot
157 avoid caching the data, it will minimize the impact the data has on the cache.
158 Use of this flag can drastically reduce performance if not used with care.
162 signal to be sent to the process group
163 when I/O is possible, e.g.,
164 upon availability of data to be read.
167 Several commands are available for doing advisory file locking;
168 they all operate on the following structure:
171 off_t l_start; /* starting offset */
172 off_t l_len; /* len = 0 means until end of file */
173 pid_t l_pid; /* lock owner */
174 short l_type; /* lock type: read/write, etc. */
175 short l_whence; /* type of l_start */
178 The commands available for advisory record locking are as follows:
179 .Bl -tag -width F_SETLKWX
181 Get the first lock that blocks the lock description pointed to by the
184 taken as a pointer to a
187 The information retrieved overwrites the information passed to
192 If no lock is found that would prevent this lock from being created,
193 the structure is left unchanged by this function call except for the
194 lock type which is set to
197 Set or clear a file segment lock according to the lock description
198 pointed to by the third argument,
200 taken as a pointer to a
204 is used to establish shared (or read) locks
206 or exclusive (or write) locks,
208 as well as remove either type of lock
210 If a shared or exclusive lock cannot be set,
212 returns immediately with
215 This command is the same as
217 except that if a shared or exclusive lock is blocked by other locks,
218 the process waits until the request can be satisfied.
219 If a signal that is to be caught is received while
221 is waiting for a region, the
223 will be interrupted if the signal handler has not specified the
229 When a shared lock has been set on a segment of a file,
230 other processes can set shared locks on that segment
232 A shared lock prevents any other process from setting an exclusive
233 lock on any portion of the protected area.
234 A request for a shared lock fails if the file descriptor was not
235 opened with read access.
237 An exclusive lock prevents any other process from setting a shared lock or
238 an exclusive lock on any portion of the protected area.
239 A request for an exclusive lock fails if the file was not
240 opened with write access.
249 to indicate that the relative offset,
251 bytes, will be measured from the start of the file,
252 current position, or end of the file, respectively.
255 is the number of consecutive bytes to be locked.
258 is negative, the result is undefined.
261 field is only used with
263 to return the process ID of the process holding a blocking lock.
266 request, the value of
271 Locks may start and extend beyond the current end of a file,
272 but may not start or extend before the beginning of the file.
273 A lock is set to extend to the largest possible value of the
274 file offset for that file if
281 point to the beginning of the file, and
283 is zero, the entire file is locked.
284 If an application wishes only to do entire file locking, the
286 system call is much more efficient.
288 There is at most one type of lock set for each byte in the file.
289 Before a successful return from an
293 request when the calling process has previously existing locks
294 on bytes in the region specified by the request,
295 the previous lock type for each byte in the specified
296 region is replaced by the new lock type.
297 As specified above under the descriptions
298 of shared locks and exclusive locks, an
302 request fails or blocks respectively when another process has existing
303 locks on bytes in the specified region and the type of any of those
304 locks conflicts with the type specified in the request.
306 This interface follows the completely stupid semantics of System V and
308 that require that all locks associated with a file for a given process are
311 file descriptor for that file is closed by that process.
312 This semantic means that applications must be aware of any files that
313 a subroutine library may access.
314 For example if an application for updating the password file locks the
315 password file database while making the update, and then calls
317 to retrieve a record,
318 the lock will be lost because
320 opens, reads, and closes the password database.
321 The database close will release all locks that the process has
322 associated with the database, even if the library routine never
323 requested a lock on the database.
324 Another minor semantic problem with this interface is that
325 locks are not inherited by a child process created using the
330 interface has much more rational last close semantics and
331 allows locks to be inherited by child processes.
333 is recommended for applications that want to ensure the integrity
334 of their locks when using library routines or wish to pass locks
340 locks may be safely used concurrently but
344 if the process holding a blocking lock previously locked the
348 All locks associated with a file for a given process are
349 removed when the process terminates.
351 All locks obtained before a call to
353 remain in effect until the new program releases them.
354 If the new program does not know about the locks, they will not be
355 released until the program exits.
357 A potential for deadlock occurs if a process controlling a locked region
358 is put to sleep by attempting to lock the locked region of another process.
359 This implementation detects that sleeping until a locked region is unlocked
360 would cause a deadlock and fails with an
364 Upon successful completion, the value returned depends on
367 .Bl -tag -width F_GETOWNX -offset indent
369 A new file descriptor.
371 Value of flag (only the low-order bit is defined).
375 Value of file descriptor owner.
380 Otherwise, a value of -1 is returned and
382 is set to indicate the error.
398 and the segment of a file to be locked is already
399 exclusive-locked by another process;
400 or the type is an exclusive lock and some portion of the
401 segment of a file to be locked is already shared-locked or
402 exclusive-locked by another process.
405 is not a valid open file descriptor.
419 is not a valid file descriptor open for reading.
433 is not a valid file descriptor open for writing.
439 and a deadlock condition was detected.
445 and the function was interrupted by a signal.
452 is negative or greater than the maximum allowable number
454 .Xr getdtablesize 2 ) .
463 and the data to which
465 points is not valid, or
467 refers to a file that does not support locking.
473 and the maximum number of file descriptors permitted for the
474 process are already in use,
475 or no file descriptors greater than or equal to
485 and satisfying the lock or unlock request would result in the
486 number of locked regions in the system exceeding a system-imposed limit.
492 the process ID or process group given as an argument is in a
493 different session than the caller.
499 the process ID given as argument is not in use.
504 refers to a descriptor open on a terminal device (as opposed to a
505 descriptor open on a socket), a
509 can fail for the same reasons as in
515 for the reasons as stated in
521 .Xr getdtablesize 2 ,
529 function call appeared in