2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
25 .\" This notice shall appear on any product containing this material.
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved.
47 .\" Copyright 2015 Joyent, Inc.
49 .TH FCNTL 2 "Feb 16, 2015"
55 #include <sys/types.h>
59 \fBint\fR \fBfcntl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcmd\fR, \fB/*\fR \fIarg\fR */ ...);
64 The \fBfcntl()\fR function provides for control over open files. The
65 \fIfildes\fR argument is an open file descriptor.
68 The \fBfcntl()\fR function can take a third argument, \fIarg\fR, whose data
69 type, value, and use depend upon the value of \fIcmd\fR. The \fIcmd\fR argument
70 specifies the operation to be performed by \fBfcntl()\fR.
73 The values for \fIcmd\fR are defined in <\fBfcntl.h\fR> and include:
80 Return a new file descriptor which is the lowest numbered available (that is,
81 not already open) file descriptor greater than or equal to the third argument,
82 \fIarg\fR, taken as an integer of type \fBint\fR. The new file descriptor
83 refers to the same open file description as the original file descriptor, and
84 shares any locks. The \fBFD_CLOEXEC\fR flag associated with the new file
85 descriptor is cleared to keep the file open across calls to one of the
86 \fBexec\fR(2) functions.
95 Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR. \fBF_DUP2FD\fR closes
96 \fIarg\fR if it is open and not equal to \fIfildes.\fR \fBF_DUP2FD\fR is
97 equivalent to \fBdup2\fR(\fIfildes\fR, \fIarg\fR).
103 \fB\fBF_DUPFD_CLOEXEC\fR\fR
106 Similar to \fBF_DUPFD\fR except that instead of clearing \fBFD_CLOEXEC\fR
107 it is explicitly set on the returned file descriptor.
113 \fB\fBF_DUP2FD_CLOEXEC\fR\fR
116 Similar to \fBF_DUP2FD\fR with two exceptions. The \fBFD_CLOEXEC\fR flag is
117 explicitly set on the returned file descriptor. If \fIfiledes\fR equals
118 \fIarg\fR, the call will fail setting \fBerrno\fR to \fBEINVAL\fR.
127 Free storage space associated with a section of the ordinary file \fIfildes\fR.
128 The section is specified by a variable of data type \fBstruct flock\fR pointed
129 to by \fIarg\fR. The data type \fBstruct flock\fR is defined in the
130 <\fBfcntl.h\fR> header (see \fBfcntl.h\fR(3HEAD)) and is described below. Note
131 that all file systems might not support all possible variations of
132 \fBF_FREESP\fR arguments. In particular, many file systems allow space to be
133 freed only at the end of a file.
139 \fB\fBF_FREESP64\fR\fR
142 Equivalent to \fBF_FREESP\fR, but takes a \fBstruct flock64\fR argument rather
143 than a \fBstruct flock\fR argument.
149 \fB\fBF_ALLOCSP\fR\fR
152 Allocate space for a section of the ordinary file \fIfildes\fR. The section is
153 specified by a variable of data type \fBstruct flock\fR pointed to by
154 \fIarg\fR. The data type \fBstruct flock\fR is defined in the <\fBfcntl.h\fR>
155 header (see \fBfcntl.h\fR(3HEAD) and is described below.
161 \fB\fBF_ALLOCSP64\fR\fR
164 Equivalent to \fBF_ALLOCSP\fR, but takes a \fBstruct flock64\fR argument rather
165 than a \fBstruct flock\fR argument.
174 Get the file descriptor flags defined in <\fBfcntl.h\fR> that are associated
175 with the file descriptor \fIfildes\fR. File descriptor flags are associated
176 with a single file descriptor and do not affect other file descriptors that
177 refer to the same file.
186 Get the file status flags and file access modes, defined in <\fBfcntl.h\fR>,
187 for the file descriptor specified by \fIfildes\fR. The file access modes can be
188 extracted from the return value using the mask \fBO_ACCMODE\fR, which is
189 defined in <\fBfcntl.h\fR>. File status flags and file access modes do not
190 affect other file descriptors that refer to the same file with different open
200 If \fIfildes\fR refers to a socket, get the process or process group \fBID\fR
201 specified to receive \fBSIGURG\fR signals when out-of-band data is available.
202 Positive values indicate a process ID; negative values, other than \(mi1,
203 indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
204 results are unspecified.
213 Get the file status flags, file access modes, and file creation and assignment
214 flags, defined in <\fBfcntl.h\fR>, for the file descriptor specified by
215 \fIfildes\fR. The file access modes can be extracted from the return value
216 using the mask \fBO_ACCMODE\fR, which is defined in <\fBfcntl.h\fR>. File
217 status flags, file access modes, and file creation and assignment flags do not
218 affect other file descriptors that refer to the same file with different open
228 Set the file descriptor flags defined in <\fBfcntl.h\fR>, that are associated
229 with \fIfildes\fR, to the third argument, \fIarg\fR, taken as type \fBint\fR.
230 If the \fBFD_CLOEXEC\fR flag in the third argument is 0, the file will remain
231 open across the \fBexec()\fR functions; otherwise the file will be closed upon
232 successful execution of one of the \fBexec()\fR functions.
241 Set the file status flags, defined in <\fBfcntl.h\fR>, for the file descriptor
242 specified by \fIfildes\fR from the corresponding bits in the \fIarg\fR
243 argument, taken as type \fBint\fR. Bits corresponding to the file access mode
244 and file creation and assignment flags that are set in \fIarg\fR are ignored.
245 If any bits in \fIarg\fR other than those mentioned here are changed by the
246 application, the result is unspecified.
255 If \fIfildes\fR refers to a socket, set the process or process group \fBID\fR
256 specified to receive \fBSIGURG\fR signals when out-of-band data is available,
257 using the value of the third argument, \fIarg\fR, taken as type \fBint\fR.
258 Positive values indicate a process ID; negative values, other than \(mi1,
259 indicate a process group ID. If \fIfildes\fR does not refer to a socket, the
260 results are unspecified.
265 The following commands are available for POSIX advisory or mandatory record
266 locking. POSIX record locking is supported for regular files, and may be
267 supported for other files. See the FILE LOCKING section of this manual page for
268 information about the types of file locks available and their interaction.
275 Get the first lock which blocks the POSIX lock description pointed to by the
276 third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
277 defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
278 information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is
279 found that would prevent this lock from being created, then the structure will
280 be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR.
281 If multiple locks exist that would prevent this lock from being created, which
282 one is returned is unspecified. If the blocking lock is an OFD-style lock,
283 \fB\(mi1\fR\& will be returned for the lock's pid value.
292 Set or clear a POSIX record lock according to the lock description pointed to
293 by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
294 flock\fR, defined in <\fBfcntl.h\fR>. \fBF_SETLK\fR is used to establish shared
295 (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR),
296 as well as to remove either type of lock (\fBF_UNLCK\fR). \fBF_RDLCK\fR,
297 \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. If a shared or
298 exclusive lock cannot be set, \fBfcntl()\fR will return immediately with a
299 return value of \fB\(mi1\fR\&.
308 This command is the same as \fBF_SETLK\fR except that if a shared or exclusive
309 lock is blocked by other locks, the process will wait until the request can be
310 satisfied. If a signal that is to be caught is received while \fBfcntl()\fR is
311 waiting for a region, \fBfcntl()\fR will be interrupted. Upon return from the
312 process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR with \fBerrno\fR
313 set to \fBEINTR\fR, and the lock operation will not be done.
318 The following commands are available for OFD (open file description) advisory
319 record locking. OFD record locking is supported for regular files, and may be
320 supported for other files. See the FILE LOCKING section of this manual page for
321 information about the types of file locks available and their interaction.
322 OFD-style record locks are currently limited to spanning the entire file and
323 these locks are currently not supported over remote file systems (e.g.
324 \fBnfs\fR(4)) which use the Network Lock Manager.
328 \fB\fBF_OFD_GETLK\fR\fR
331 Get the first lock which blocks the OFD lock description pointed to by the
332 third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR,
333 defined in <\fBfcntl.h\fR>. The information retrieved overwrites the
334 information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is
335 found that would prevent this lock from being created, then the structure will
336 be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR.
337 If multiple locks exist that would prevent this lock from being created, which
338 one is returned is unspecified. If the blocking lock is an OFD-style lock,
339 \fB\(mi1\fR\& will be returned for the lock's pid value.
345 \fB\fBF_OFD_SETLK\fR\fR
348 Set or clear a OFD record lock according to the lock description pointed to
349 by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct
350 flock\fR, defined in <\fBfcntl.h\fR>. \fBF_OFD_SETLK\fR is used to establish
351 shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks
352 (\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR).
353 \fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>.
354 If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return
355 immediately with a return value of \fB\(mi1\fR\&.
361 \fB\fBF_OFD_SETLKW\fR\fR
364 This command is the same as \fBF_OFD_SETLK\fR except that if a shared or
365 exclusive lock is blocked by other locks, the process will wait until the
366 request can be satisfied. If a signal that is to be caught is received while
367 \fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon
368 return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR
369 with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done.
374 The following values for \fIcmd\fR are used for file share reservations. A
375 share reservation is placed on an entire file to allow cooperating processes to
376 control access to the file. See the SHARE RESERVATIONS section of this manual
377 page below for additional information.
384 Sets a share reservation on a file with the specified access mode and
385 designates which types of access to deny.
391 \fB\fBF_UNSHARE\fR\fR
394 Remove an existing share reservation.
399 Two types of file locks are supported: POSIX-style and OFD-style. OFD-style
400 locks are associated with the open file description (not descriptor) instead
401 of with a process. Either type is advisory by default, but POSIX-style locks
402 can be mandatory if, and only if, mandatory locking has been enabled on the
403 file being locked. Each type of lock may be created through two different
404 interfaces. POSIX-style locks are created via the \fBF_SETLK\fR,
405 \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR commands to this system
406 call or by use of the \fBlockf\fR(3C) routine. There is no difference between
407 locks created via one mechanism or the other. Likewise, OFD-style locks are
408 created via the \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
409 \fBF_OFD_SETLKW64\fR commands to this system call or by use of the
410 Linux/BSD-compatible \fBflock\fR(3C) routine. Note that this system call
411 supports the creation of range-specified OFD-style file locks, while
412 \fBflock\fR(3C) does not. However, the current implementation of OFD-style
413 locking is limited to locking the entire file. This limitation might be
414 removed in the future.
417 The essential distinction between POSIX-style locks and OFD-style locks lie
418 in how ownership of a lock is scoped. POSIX locks are scoped to a process. All
419 POSIX locks associated with a file for a given process are removed when any
420 file descriptor for that file is closed by that process or the process holding
421 that file descriptor terminates. POSIX-style locks are not inherited by a child
422 process created using \fBfork\fR(2). An OFD-style lock is scoped to the file
423 description for a file, not the process or open file descriptor. Thus all file
424 descriptors referring to the same description (i.e. those created via the
425 \fBF_DUPFD\fR, \fBF_DUP2FD\fR, \fBF_DUPFD_CLOEXEC\fR, or \fBF_DUP2FD_CLOEXEC\fR
426 commands to the \fBfcntl\fR(2) system call, or those created via the
427 \fBdup\fR(2) system call, or those inherited by a child process created via
428 \fBfork\fR(2)) reference the same lock, but a file descriptor obtained via a
429 separate \fBopen\fR(2) call on the same file will reference a different lock.
430 A lock is removed only on the last \fBclose\fR(2) of the description, or when
431 the lock is explicitly unlocked.
434 Locks of both styles are compatible. A file that has been locked with one
435 style of lock will be regarded as locked when creation of a lock of either
436 style is attempted, and information about the lock will be provided via
437 any of the \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or
438 \fBF_OFD_GETLK64\fR commands to this system call if that lock would conflict
439 with an attempt to create the specified lock regardless of whether the
440 specified lock is of the same style as the conflicting extant lock.
441 Because ownership of OFD-style locks is scoped to the open description rather
442 than the calling process, the \fBl_pid\fR field of a lock descriptor for any
443 such lock will always be set to \fB\(mi1\fR\&.
446 When a shared lock is set on a segment of a file, other callers (regardless
447 of whether in the same or different process and of whether referenced via the
448 same open file) will be able to set shared locks on that segment or a portion
449 of it. A POSIX-style shared lock prevents any other process from setting an
450 exclusive lock on any portion of the protected area. A OFD-style shared lock
451 prevents any caller (even callers in the same process) from setting an
452 exclusive lock on any portion of the protected area, unless the caller makes
453 the request against a file descriptor referencing the same open file against
454 which the shared lock was created, in which case the lock will be downgraded
455 to a shared lock with respect to the specified region. A request for a shared
456 lock of either style will fail if the file descriptor was not opened with
460 A POSIX-style exclusive lock will prevent any other process from setting a
461 shared lock or an exclusive lock (of either style) on any portion of the
462 protected area. A request for an exclusive lock will fail if the file
463 descriptor was not opened with write access.
466 The \fBflock\fR structure contains at least the following elements:
470 short l_type; /* lock operation type */
471 short l_whence; /* lock base indicator */
472 off_t l_start; /* starting offset from base */
473 off_t l_len; /* lock length; l_len == 0 means
475 int l_sysid; /* system ID running process holding lock */
476 pid_t l_pid; /* process ID of process holding lock */
482 The value of \fBl_whence\fR is \fBSEEK_SET\fR, \fBSEEK_CUR\fR, or
483 \fBSEEK_END\fR, to indicate that the relative offset \fBl_start\fR bytes will
484 be measured from the start of the file, current position or end of the file,
485 respectively. The value of \fBl_len\fR is the number of consecutive bytes to be
486 locked. The value of \fBl_len\fR may be negative (where the definition of
487 \fBoff_t\fR permits negative values of \fBl_len\fR). After a successful
488 \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR
489 request, that is, one in which a lock was found, the value of \fBl_whence\fR
490 will be \fBSEEK_SET\fR.
493 The \fBl_pid\fR and \fBl_sysid\fR fields are used only with \fBF_GETLK\fR or
494 \fBF_GETLK64\fR to return the process \fBID\fR of the process holding a
495 POSIX-style blocking lock and to indicate which system is running that process,
496 or \fB\(mi1\fR\& if it is an OFD-style lock. These fields must both be
497 initialized to 0 prior to issuing a OFD-style locking command
498 (\fBF_OFD_GETLK\fR or \fBF_OFD_GETLK64\fR).
501 If \fBl_len\fR is positive, the area affected starts at \fBl_start\fR and ends
502 at \fBl_start\fR + \fBl_len \(mi 1\fR. If \fBl_len\fR is negative, the area
503 affected starts at \fBl_start\fR + \fBl_len\fR and ends at \fBl_start \(mi
504 1\fR. Locks may start and extend beyond the current end of a file, but must not
505 be negative relative to the beginning of the file. A lock will be set to extend
506 to the largest possible value of the file offset for that file by setting
507 \fBl_len\fR to 0. If such a lock also has \fBl_start\fR set to 0 and
508 \fBl_whence\fR is set to \fBSEEK_SET\fR, the whole file will be locked.
511 If a lock exists for which \fBl_len\fR is 0 and which includes the last byte of
512 the requested segment, and an unlock (\fBF_UNLCK\fR) request is made in which
513 \fBl_len\fR is non-zero and the offset of the last byte of the requested
514 segment is the maximum value for an object of type \fBoff_t\fR, then the
515 \fBF_UNLCK\fR request will be treated as a request to unlock from the start
516 of the requested segment with an \fBl_len\fR equal to 0. Otherwise, the request
517 will attempt to unlock only the requested segment.
520 There will be at most one type of lock set for each byte in the
521 file. Before a successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR,
522 \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request when the calling process has
523 previously existing POSIX-style locks on bytes in the region specified by the
524 request, the previous POSIX-style lock type for each byte in the specified
525 region will be replaced by the new lock type. As specified above under the
526 descriptions of shared locks and exclusive locks, an \fBF_SETLK\fR,
527 \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request will
528 (respectively) fail or block when locks exist on bytes in the specified region
529 and the type of any of those locks conflicts with the type specified in the
533 Similarly, before a successful return from an \fBF_OFD_SETLK\fR,
534 \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR request when
535 previously-created OFD-style locks associated with the open file apply to
536 bytes in the region specified by the request, the previous OFD-style lock type
537 for each byte in the specified region will be replaced by the new lock type.
538 As specified above under the descriptions of shared locks and exclusive locks,
539 an \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
540 \fBF_OFD_SETLKW64\fR request will (respectively) fail or block when locks exist
541 on bytes in the specified region and the type of any of those locks conflicts
542 with the type specified in the request.
545 A potential for deadlock occurs if a process controlling a locked region is put
546 to sleep by attempting to lock another process' locked region. If the system
547 detects that sleeping until a locked region is unlocked would cause a deadlock,
548 \fBfcntl()\fR will fail with an \fBEDEADLK\fR error. This deadlock detection
549 and error value apply only to POSIX-style locks. No deadlock detection is
550 performed when attempting to set an OFD-style lock.
552 .SH SHARE RESERVATIONS
554 File share reservations are an advisory form of access control among
555 cooperating processes, on both local and remote machines. They are most often
556 used by \fBDOS\fR or Windows emulators and \fBDOS based\fR \fBNFS\fR clients.
557 However, native UNIX versions of \fBDOS\fR or Windows applications may also
558 choose to use this form of access control.
561 A share reservation is described by an \fBfshare\fR structure defined in
562 <\fBsys/fcntl.h\fR>, which is included in <\fBfcntl.h\fR> as follows:
566 typedef struct fshare {
576 A share reservation specifies the type of access, \fBf_access\fR, to be
577 requested on the open file descriptor. If access is granted, it further
578 specifies what type of access to deny other processes, \fBf_deny\fR. A single
579 process on the same file may hold multiple non-conflicting reservations by
580 specifying an identifier, \fBf_id\fR, unique to the process, with each request.
583 An \fBF_UNSHARE\fR request releases the reservation with the specified
584 \fBf_id\fR. The \fBf_access\fR and \fBf_deny\fR fields are ignored.
587 Valid \fBf_access\fR values are:
594 Set a file share reservation for read-only access.
603 Set a file share reservation for write-only access.
612 Set a file share reservation for read and write access.
617 Valid \fBf_deny\fR values are:
624 Set a file share reservation to compatibility mode.
633 Set a file share reservation to deny read access to other processes.
642 Set a file share reservation to deny write access to other processes.
651 Set a file share reservation to deny read and write access to other processes.
660 Do not deny read or write access to any other process.
665 Upon successful completion, the value returned depends on \fIcmd\fR as follows:
672 A new file descriptor.
690 Value of flags defined in \fB<fcntl.h>\fR\&. The return value will not be
700 Value of file status flags and access modes. The return value will not be
710 Value other than \fB\(mi1\fR\&.
716 \fB\fBF_GETLK64\fR\fR
719 Value other than \fB\(mi1\fR\&.
728 Value of the socket owner process or process group; this will not be
738 Value of file status flags, access modes, and creation and assignment flags.
739 The return value will not be negative.
745 \fB\fBF_OFD_GETLK\fR\fR
748 Value other then \fB\(mi1\fR\&.
754 \fB\fBF_OFD_GETLK64\fR\fR
757 Value other then \fB\(mi1\fR\&.
763 \fB\fBF_OFD_SETLK\fR\fR
766 Value other then \fB\(mi1\fR\&.
772 \fB\fBF_OFD_SETLK64\fR\fR
775 Value other then \fB\(mi1\fR\&.
781 \fB\fBF_OFD_SETLKW\fR\fR
784 Value other then \fB\(mi1\fR\&.
790 \fB\fBF_OFD_SETLKW64\fR\fR
793 Value other then \fB\(mi1\fR\&.
802 Value other than \fB\(mi1\fR\&.
811 Value other than \fB\(mi1\fR\&.
820 Value other than \fB\(mi1\fR\&.
826 \fB\fBF_SETLK64\fR\fR
829 Value other than \fB\(mi1\fR\&.
838 Value other than \fB\(mi1\fR\&.
844 \fB\fBF_SETLKW64\fR\fR
847 Value other than \fB\(mi1\fR\&.
856 Value other than \fB\(mi1\fR\&.
865 Value other than \fB\(mi1\fR\&.
871 \fB\fBF_UNSHARE\fR\fR
874 Value other than \fB\(mi1\fR\&.
879 Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the
883 The \fBfcntl()\fR function will fail if:
890 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_OFD_SETLK\fR,
891 or \fBF_OFD_SETLK64\fR, the type of lock \fB(l_type)\fR is a shared
892 (\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) lock, and the segment of a file
893 to be locked is already exclusive-locked by another process or open file; or
894 the type is an exclusive lock and some portion of the segment of a file to be
895 locked is already shared-locked or exclusive-locked by another process or open
898 The \fIcmd\fR argument is \fBF_FREESP\fR, the file exists, mandatory
899 file/record locking is set, and there are outstanding record locks on the file;
900 or the \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or
901 \fBF_SETLKW64\fR, mandatory file/record locking is set, and the file is
902 currently being mapped to virtual memory using \fBmmap\fR(2).
904 The \fIcmd\fR argument is \fBF_SHARE\fR and \fBf_access\fR conflicts with an
905 existing \fBf_deny\fR share reservation.
914 The \fIfildes\fR argument is not a valid open file descriptor; or the \fIcmd\fR
915 argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR,
916 \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or
917 \fBF_OFD_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock
918 (\fBF_RDLCK\fR), and \fIfildes\fR is not a valid file descriptor open for
919 reading; or the type of lock \fBl_type\fR is an exclusive lock (\fBF_WRLCK\fR)
920 and \fIfildes\fR is not a valid file descriptor open for writing.
922 The \fIcmd\fR argument is \fBF_FREESP\fR and \fIfildes\fR is not a valid file
923 descriptor open for writing.
925 The \fIcmd\fR argument is \fBF_DUP2FD\fR, and \fIarg\fR is negative or is not
926 less than the current resource limit for \fBRLIMIT_NOFILE.\fR
928 The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
929 is for write access, and \fIfildes\fR is not a valid file descriptor open for
932 The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation
933 is for read access, and \fIfildes\fR is not a valid file descriptor open for
943 The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR,
944 \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR,
945 \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
946 \fBF_OFD_SETLKW64\fR, \fBF_SHARE\fR, \fBF_UNSHARE\fR, or \fBF_FREESP\fR and the
947 \fIarg\fR argument points to an illegal address.
956 The \fIcmd\fR argument is \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLKW\fR,
957 or \fBF_OFD_SETLKW64\fR, and the function was interrupted by a signal.
966 The \fIcmd\fR argument is invalid or not supported by the file system; or the
967 \fIcmd\fR argument is \fBF_DUPFD\fR and \fIarg\fR is negative or greater than
968 or equal to \fBOPEN_MAX\fR; or the \fIcmd\fR argument is \fBF_GETLK\fR,
969 \fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
970 \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR,
971 \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the data
972 pointed to by \fIarg\fR is not valid; or \fIfildes\fR refers to a file that
973 does not support locking.
975 The \fIcmd\fR argument is \fBF_UNSHARE\fR and a reservation with this
976 \fBf_id\fR for this process does not exist.
978 The \fIcmd\fR argument is \fBF_DUP2FD_CLOEXEC\fR and \fIfildes\fR is equal
988 An I/O error occurred while reading from or writing to the file system.
997 The \fIcmd\fR argument is \fBF_DUPFD\fR and either \fBOPEN_MAX\fR file
998 descriptors are currently open in the calling process, or no file descriptors
999 greater than or equal to \fIarg\fR are available.
1008 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
1009 \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
1010 or \fBF_OFD_SETLKW64\fR, and satisfying the lock or unlock request would
1011 result in the number of locked regions in the system exceeding a
1012 system-imposed limit.
1021 Either the \fIfildes\fR argument is on a remote machine and the link to that
1022 machine is no longer active; or the \fIcmd\fR argument is \fBF_FREESP\fR, the
1023 file is on a remote machine, and the link to that machine is no longer active.
1029 \fB\fBEOVERFLOW\fR\fR
1032 One of the values to be returned cannot be represented correctly.
1034 The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, \fBF_SETLKW\fR,
1035 \fBF_OFD_GETLK\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLKW\fR, and
1036 the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in
1037 the requested segment cannot be represented correctly in an object of type
1040 The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, \fBF_SETLKW64\fR,
1041 \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK64\fR, or \fBF_OFD_SETLKW64\fR,
1042 and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any
1043 byte in the requested segment cannot be represented correctly in an object of
1049 The \fBfcntl()\fR function may fail if:
1056 The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR,
1057 \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR,
1058 or \fBF_OFD_SETLKW64\fR and the file is currently being mapped to virtual memory
1059 using \fBmmap\fR(2).
1068 The \fIcmd\fR argument is \fBF_SETLKW\fR or \fBF_SETLKW64\fR, the lock is
1069 blocked by some lock from another process and putting the calling process to
1070 sleep, waiting for that lock to become free would cause a deadlock.
1072 The \fIcmd\fR argument is \fBF_FREESP,\fR mandatory record locking is enabled,
1073 \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear and a deadlock condition was
1079 See \fBattributes\fR(5) for descriptions of the following attributes:
1087 ATTRIBUTE TYPE ATTRIBUTE VALUE
1089 Interface Stability Standard
1091 MT-Level Async-Signal Safe
1096 \fBlockd\fR(8), \fBchmod\fR(2), \fBclose\fR(2), \fBcreat\fR(2), \fBdup\fR(2),
1097 \fBexec\fR(2), \fBfork\fR(2), \fBmmap\fR(2), \fBopen\fR(2), \fBpipe\fR(2),
1098 \fBread\fR(2), \fBsigaction\fR(2), \fBwrite\fR(2), \fBdup2\fR(3C),
1099 \fBflock\fR(3C), \fBlockf\fR(3C), \fBfcntl.h\fR(3HEAD), \fBattributes\fR(5),
1103 \fIProgramming Interfaces Guide\fR
1106 In the past, the variable \fBerrno\fR was set to \fBEACCES\fR rather than
1107 \fBEAGAIN\fR when a section of a file is already locked by another process.
1108 Therefore, portable application programs should expect and test for either
1112 Advisory locks allow cooperating processes to perform consistent operations on
1113 files, but do not guarantee exclusive access. Files can be accessed without
1114 advisory locks, but inconsistencies may result. The network share locking
1115 protocol does not support the \fBf_deny\fR value of \fBF_COMPAT\fR. For network
1116 file systems, if \fBf_access\fR is \fBF_RDACC\fR, \fBf_deny\fR is mapped to
1117 \fBF_RDDNY\fR. Otherwise, it is mapped to \fBF_RWDNY\fR.
1120 To prevent possible file corruption, the system may reject \fBmmap()\fR
1121 requests for advisory locked files, or it may reject advisory locking requests
1122 for mapped files. Applications that require a file be both locked and mapped
1123 should lock the entire file (\fBl_start\fR and \fBl_len\fR both set to 0). If a
1124 file is mapped, the system may reject an unlock request, resulting in a lock
1125 that does not cover the entire file.
1128 The process ID returned for locked files on network file systems might not be
1132 If the file server crashes and has to be rebooted, the lock manager (see
1133 \fBlockd\fR(8)) attempts to recover all locks that were associated with that
1134 server. If a lock cannot be reclaimed, the process that held the lock is issued
1135 a \fBSIGLOST\fR signal.