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
46 .Fn fcntl "int fd" "int cmd" "..."
50 system call provides for control over descriptors.
53 is a descriptor to be operated on by
56 Depending on the value of
59 can take an additional third argument
61 .Bl -tag -width F_GETOWNX
63 Return a new descriptor as follows:
65 .Bl -bullet -compact -offset 4n
67 Lowest numbered available descriptor greater than or equal to
70 Same object references as the original descriptor.
72 New descriptor shares the same file offset if the object
75 Same access mode (read, write or read/write).
77 Same file status flags (i.e., both file descriptors
78 share the same file status flags).
80 The close-on-exec flag associated with the new file descriptor
81 is set to remain open across
86 Get the close-on-exec flag associated with the file descriptor
90 If the returned value ANDed with
93 the file will remain open across
95 otherwise the file will be closed upon execution of
100 Set the close-on-exec flag associated with
110 Get descriptor status flags, as described below
114 Set descriptor status flags to
117 Get the process ID or process group
122 signals; process groups are returned
127 Set the process or process group
133 process groups are specified by supplying
135 as negative, otherwise
137 is interpreted as a process ID.
144 flags are as follows:
145 .Bl -tag -width O_NONBLOCKX
147 Non-blocking I/O; if no data is available to a
151 operation would block,
152 the read or write call returns -1 with the error
155 Force each write to append at the end of file;
161 Minimize or eliminate the cache effects of reading and writing.
163 will attempt to avoid caching the data you read or write.
165 avoid caching the data, it will minimize the impact the data has on the cache.
166 Use of this flag can drastically reduce performance if not used with care.
170 signal to be sent to the process group
171 when I/O is possible, e.g.,
172 upon availability of data to be read.
175 Several commands are available for doing advisory file locking;
176 they all operate on the following structure:
179 off_t l_start; /* starting offset */
180 off_t l_len; /* len = 0 means until end of file */
181 pid_t l_pid; /* lock owner */
182 short l_type; /* lock type: read/write, etc. */
183 short l_whence; /* type of l_start */
186 The commands available for advisory record locking are as follows:
187 .Bl -tag -width F_SETLKWX
189 Get the first lock that blocks the lock description pointed to by the
192 taken as a pointer to a
195 The information retrieved overwrites the information passed to
200 If no lock is found that would prevent this lock from being created,
201 the structure is left unchanged by this system call except for the
202 lock type which is set to
205 Set or clear a file segment lock according to the lock description
206 pointed to by the third argument,
208 taken as a pointer to a
212 is used to establish shared (or read) locks
214 or exclusive (or write) locks,
216 as well as remove either type of lock
218 If a shared or exclusive lock cannot be set,
220 returns immediately with
223 This command is the same as
225 except that if a shared or exclusive lock is blocked by other locks,
226 the process waits until the request can be satisfied.
227 If a signal that is to be caught is received while
229 is waiting for a region, the
231 will be interrupted if the signal handler has not specified the
237 When a shared lock has been set on a segment of a file,
238 other processes can set shared locks on that segment
240 A shared lock prevents any other process from setting an exclusive
241 lock on any portion of the protected area.
242 A request for a shared lock fails if the file descriptor was not
243 opened with read access.
245 An exclusive lock prevents any other process from setting a shared lock or
246 an exclusive lock on any portion of the protected area.
247 A request for an exclusive lock fails if the file was not
248 opened with write access.
257 to indicate that the relative offset,
259 bytes, will be measured from the start of the file,
260 current position, or end of the file, respectively.
263 is the number of consecutive bytes to be locked.
268 means end edge of the region.
271 field is only used with
273 to return the process ID of the process holding a blocking lock.
276 request, the value of
281 Locks may start and extend beyond the current end of a file,
282 but may not start or extend before the beginning of the file.
283 A lock is set to extend to the largest possible value of the
284 file offset for that file if
291 point to the beginning of the file, and
293 is zero, the entire file is locked.
294 If an application wishes only to do entire file locking, the
296 system call is much more efficient.
298 There is at most one type of lock set for each byte in the file.
299 Before a successful return from an
303 request when the calling process has previously existing locks
304 on bytes in the region specified by the request,
305 the previous lock type for each byte in the specified
306 region is replaced by the new lock type.
307 As specified above under the descriptions
308 of shared locks and exclusive locks, an
312 request fails or blocks respectively when another process has existing
313 locks on bytes in the specified region and the type of any of those
314 locks conflicts with the type specified in the request.
316 This interface follows the completely stupid semantics of System V and
318 that require that all locks associated with a file for a given process are
321 file descriptor for that file is closed by that process.
322 This semantic means that applications must be aware of any files that
323 a subroutine library may access.
324 For example if an application for updating the password file locks the
325 password file database while making the update, and then calls
327 to retrieve a record,
328 the lock will be lost because
330 opens, reads, and closes the password database.
331 The database close will release all locks that the process has
332 associated with the database, even if the library routine never
333 requested a lock on the database.
334 Another minor semantic problem with this interface is that
335 locks are not inherited by a child process created using the
340 interface has much more rational last close semantics and
341 allows locks to be inherited by child processes.
344 system call is recommended for applications that want to ensure the integrity
345 of their locks when using library routines or wish to pass locks
353 locks are compatible.
354 Processes using different locking interfaces can cooperate
355 over the same file safely.
356 However, only one of such interfaces should be used within
358 If a file is locked by a process through
360 any record within the file will be seen as locked
361 from the viewpoint of another process using
370 if the process holding a blocking lock previously locked the
374 All locks associated with a file for a given process are
375 removed when the process terminates.
377 All locks obtained before a call to
379 remain in effect until the new program releases them.
380 If the new program does not know about the locks, they will not be
381 released until the program exits.
383 A potential for deadlock occurs if a process controlling a locked region
384 is put to sleep by attempting to lock the locked region of another process.
385 This implementation detects that sleeping until a locked region is unlocked
386 would cause a deadlock and fails with an
390 Upon successful completion, the value returned depends on
393 .Bl -tag -width F_GETOWNX -offset indent
395 A new file descriptor.
397 Value of flag (only the low-order bit is defined).
401 Value of file descriptor owner.
406 Otherwise, a value of -1 is returned and
408 is set to indicate the error.
412 system call will fail if:
425 and the segment of a file to be locked is already
426 exclusive-locked by another process;
427 or the type is an exclusive lock and some portion of the
428 segment of a file to be locked is already shared-locked or
429 exclusive-locked by another process.
434 is not a valid open file descriptor.
448 is not a valid file descriptor open for reading.
462 is not a valid file descriptor open for writing.
468 and a deadlock condition was detected.
474 and the system call was interrupted by a signal.
483 is negative or greater than the maximum allowable number
485 .Xr getdtablesize 2 ) .
494 and the data to which
502 and the maximum number of file descriptors permitted for the
503 process are already in use,
504 or no file descriptors greater than or equal to
514 and satisfying the lock or unlock request would result in the
515 number of locked regions in the system exceeding a system-imposed limit.
526 refers to a file for which locking is not supported.
537 calculation overflowed.
545 the process ID or process group given as an argument is in a
546 different session than the caller.
554 the process ID given as argument is not in use.
559 refers to a descriptor open on a terminal device (as opposed to a
560 descriptor open on a socket), a
564 can fail for the same reasons as in
570 for the reasons as stated in
576 .Xr getdtablesize 2 ,
585 system call appeared in