.\" .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for .\" permission to reproduce portions of its copyrighted documentation. .\" Original documentation from The Open Group can be obtained online at .\" http://www.opengroup.org/bookstore/. .\" .\" The Institute of Electrical and Electronics Engineers and The Open .\" Group, have given us permission to reprint portions of their .\" documentation. .\" .\" In the following statement, the phrase ``this text'' refers to portions .\" of the system documentation. .\" .\" Portions of this text are reprinted and reproduced in electronic form .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, .\" Standard for Information Technology -- Portable Operating System .\" Interface (POSIX), The Open Group Base Specifications Issue 6, .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics .\" Engineers, Inc and The Open Group. In the event of any discrepancy .\" between these versions and the original IEEE and The Open Group .\" Standard, the original IEEE and The Open Group Standard is the referee .\" document. The original Standard can be obtained online at .\" http://www.opengroup.org/unix/online.html. .\" .\" This notice shall appear on any product containing this material. .\" .\" The contents of this file are subject to the terms of the .\" Common Development and Distribution License (the "License"). .\" You may not use this file except in compliance with the License. .\" .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE .\" or http://www.opensolaris.org/os/licensing. .\" See the License for the specific language governing permissions .\" and limitations under the License. .\" .\" When distributing Covered Code, include this CDDL HEADER in each .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. .\" If applicable, add the following below this CDDL HEADER, with the .\" fields enclosed by brackets "[]" replaced with your own identifying .\" information: Portions Copyright [yyyy] [name of copyright owner] .\" .\" .\" Copyright 1989 AT&T .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. .\" Copyright (c) 2013, OmniTI Computer Consulting, Inc. All rights reserved. .\" Copyright 2015 Joyent, Inc. .\" Copyright 2022 Oxide Computer Company .\" .TH FCNTL 2 "Feb 16, 2015" .SH NAME fcntl \- file control .SH SYNOPSIS .nf #include #include #include \fBint\fR \fBfcntl\fR(\fBint\fR \fIfildes\fR, \fBint\fR \fIcmd\fR, \fB/*\fR \fIarg\fR */ ...); .fi .SH DESCRIPTION The \fBfcntl()\fR function provides for control over open files. The \fIfildes\fR argument is an open file descriptor. .sp .LP The \fBfcntl()\fR function can take a third argument, \fIarg\fR, whose data type, value, and use depend upon the value of \fIcmd\fR. The \fIcmd\fR argument specifies the operation to be performed by \fBfcntl()\fR. .sp .LP The values for \fIcmd\fR are defined in <\fBfcntl.h\fR> and include: .sp .ne 2 .na \fB\fBF_DUPFD\fR\fR .ad .RS 15n Return a new file descriptor which is the lowest numbered available (that is, not already open) file descriptor greater than or equal to the third argument, \fIarg\fR, taken as an integer of type \fBint\fR. The new file descriptor refers to the same open file description as the original file descriptor, and shares any locks. The \fBFD_CLOEXEC\fR flag associated with the new file descriptor is cleared to keep the file open across calls to one of the \fBexec\fR(2) functions. .RE .sp .ne 2 .na \fB\fBF_DUP2FD\fR\fR .ad .RS 15n Similar to \fBF_DUPFD\fR, but always returns \fIarg\fR. \fBF_DUP2FD\fR closes \fIarg\fR if it is open and not equal to \fIfildes.\fR \fBF_DUP2FD\fR is equivalent to \fBdup2\fR(\fIfildes\fR, \fIarg\fR). .RE .sp .ne 2 .na \fB\fBF_DUPFD_CLOEXEC\fR\fR .ad .RS 15n Similar to \fBF_DUPFD\fR except that instead of clearing \fBFD_CLOEXEC\fR it is explicitly set on the returned file descriptor. .RE .sp .ne 2 .na \fB\fBF_DUP2FD_CLOEXEC\fR\fR .ad .RS 15n Similar to \fBF_DUP2FD\fR with two exceptions. The \fBFD_CLOEXEC\fR flag is explicitly set on the returned file descriptor. If \fIfiledes\fR equals \fIarg\fR, the call will fail setting \fBerrno\fR to \fBEINVAL\fR. .RE .sp .ne 2 .na \fB\fBF_FREESP\fR\fR .ad .RS 15n Free storage space associated with a section of the ordinary file \fIfildes\fR. The section is specified by a variable of data type \fBstruct flock\fR pointed to by \fIarg\fR. The data type \fBstruct flock\fR is defined in the <\fBfcntl.h\fR> header (see \fBfcntl.h\fR(3HEAD)) and is described below. Note that all file systems might not support all possible variations of \fBF_FREESP\fR arguments. In particular, many file systems allow space to be freed only at the end of a file. .RE .sp .ne 2 .na \fB\fBF_FREESP64\fR\fR .ad .RS 15n Equivalent to \fBF_FREESP\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. .RE .sp .ne 2 .na \fB\fBF_ALLOCSP\fR\fR .ad .RS 15n Allocate space for a section of the ordinary file \fIfildes\fR. The section is specified by a variable of data type \fBstruct flock\fR pointed to by \fIarg\fR. The data type \fBstruct flock\fR is defined in the <\fBfcntl.h\fR> header (see \fBfcntl.h\fR(3HEAD) and is described below. .RE .sp .ne 2 .na \fB\fBF_ALLOCSP64\fR\fR .ad .RS 15n Equivalent to \fBF_ALLOCSP\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. .RE .sp .ne 2 .na \fB\fBF_GETFD\fR\fR .ad .RS 15n Get the file descriptor flags defined in <\fBfcntl.h\fR> that are associated with the file descriptor \fIfildes\fR. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. .RE .sp .ne 2 .na \fB\fBF_GETFL\fR\fR .ad .RS 15n Get the file status flags and file access modes, defined in <\fBfcntl.h\fR>, for the file descriptor specified by \fIfildes\fR. The file access modes can be extracted from the return value using the mask \fBO_ACCMODE\fR, which is defined in <\fBfcntl.h\fR>. File status flags and file access modes do not affect other file descriptors that refer to the same file with different open file descriptions. .RE .sp .ne 2 .na \fB\fBF_GETOWN\fR\fR .ad .RS 15n If \fIfildes\fR refers to a socket, get the process or process group \fBID\fR specified to receive \fBSIGURG\fR signals when out-of-band data is available. Positive values indicate a process ID; negative values, other than \(mi1, indicate a process group ID. If \fIfildes\fR does not refer to a socket, the results are unspecified. .RE .sp .ne 2 .na \fB\fBF_GETXFL\fR\fR .ad .RS 15n Get the file status flags, file access modes, and file creation and assignment flags, defined in <\fBfcntl.h\fR>, for the file descriptor specified by \fIfildes\fR. The file access modes can be extracted from the return value using the mask \fBO_ACCMODE\fR, which is defined in <\fBfcntl.h\fR>. File status flags, file access modes, and file creation and assignment flags do not affect other file descriptors that refer to the same file with different open file descriptions. .RE .sp .ne 2 .na \fB\fBF_SETFD\fR\fR .ad .RS 15n Set the file descriptor flags defined in <\fBfcntl.h\fR>, that are associated with \fIfildes\fR, to the third argument, \fIarg\fR, taken as type \fBint\fR. If the \fBFD_CLOEXEC\fR flag in the third argument is 0, the file will remain open across the \fBexec()\fR functions; otherwise the file will be closed upon successful execution of one of the \fBexec()\fR functions. .RE .sp .ne 2 .na \fB\fBF_SETFL\fR\fR .ad .RS 15n Set the file status flags, defined in <\fBfcntl.h\fR>, for the file descriptor specified by \fIfildes\fR from the corresponding bits in the \fIarg\fR argument, taken as type \fBint\fR. Bits corresponding to the file access mode and file creation and assignment flags that are set in \fIarg\fR are ignored. If any bits in \fIarg\fR other than those mentioned here are changed by the application, the result is unspecified. .RE .sp .ne 2 .na \fB\fBF_SETOWN\fR\fR .ad .RS 15n If \fIfildes\fR refers to a socket, set the process or process group \fBID\fR specified to receive \fBSIGURG\fR signals when out-of-band data is available, using the value of the third argument, \fIarg\fR, taken as type \fBint\fR. Positive values indicate a process ID; negative values, other than \(mi1, indicate a process group ID. If \fIfildes\fR does not refer to a socket, the results are unspecified. .RE .sp .LP The following commands are available for POSIX advisory or mandatory record locking. POSIX record locking is supported for regular files, and may be supported for other files. See the FILE LOCKING section of this manual page for information about the types of file locks available and their interaction. .sp .ne 2 .na \fB\fBF_GETLK\fR\fR .ad .RS 14n Get the first lock which blocks the POSIX lock description pointed to by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in <\fBfcntl.h\fR>. The information retrieved overwrites the information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is found that would prevent this lock from being created, then the structure will be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR. If multiple locks exist that would prevent this lock from being created, which one is returned is unspecified. If the blocking lock is an OFD-style lock, \fB\(mi1\fR\& will be returned for the lock's pid value. .RE .sp .ne 2 .na \fB\fBF_GETLK64\fR\fR .ad .RS 14n Equivalent to \fBF_GETLK\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). .RE .sp .ne 2 .na \fB\fBF_SETLK\fR\fR .ad .RS 14n Set or clear a POSIX record lock according to the lock description pointed to by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in <\fBfcntl.h\fR>. \fBF_SETLK\fR is used to establish shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR). \fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return immediately with a return value of \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETLK64\fR\fR .ad .RS 14n Equivalent to \fBF_SETLK\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). .RE .sp .ne 2 .na \fB\fBF_SETLKW\fR\fR .ad .RS 14n This command is the same as \fBF_SETLK\fR except that if a shared or exclusive lock is blocked by other locks, the process will wait until the request can be satisfied. If a signal that is to be caught is received while \fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done. .RE .sp .ne 2 .na \fB\fBF_SETLKW64\fR\fR .ad .RS 14n Equivalent to \fBF_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). .RE .sp .LP The following commands are available for OFD (open file description) advisory record locking. OFD record locking is supported for regular files, and may be supported for other files. See the FILE LOCKING section of this manual page for information about the types of file locks available and their interaction. OFD-style record locks are currently limited to spanning the entire file and these locks are currently not supported over remote file systems (e.g. \fBnfs\fR(5)) which use the Network Lock Manager. .sp .ne 2 .na \fB\fBF_OFD_GETLK\fR\fR .ad .RS 14n Get the first lock which blocks the OFD lock description pointed to by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in <\fBfcntl.h\fR>. The information retrieved overwrites the information passed to \fBfcntl()\fR in the structure \fBflock\fR. If no lock is found that would prevent this lock from being created, then the structure will be left unchanged except for the lock type which will be set to \fBF_UNLCK\fR. If multiple locks exist that would prevent this lock from being created, which one is returned is unspecified. If the blocking lock is an OFD-style lock, \fB\(mi1\fR\& will be returned for the lock's pid value. .RE .sp .ne 2 .na \fB\fBF_OFD_GETLK64\fR\fR .ad .RS 14n Equivalent to \fBF_OFD_GETLK\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). This command exists solely to allow the use of OFD locks with the transitional 64-bit file interfaces. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLK\fR\fR .ad .RS 14n Set or clear a OFD record lock according to the lock description pointed to by the third argument, \fIarg\fR, taken as a pointer to type \fBstruct flock\fR, defined in <\fBfcntl.h\fR>. \fBF_OFD_SETLK\fR is used to establish shared (or read) locks (\fBF_RDLCK\fR) or exclusive (or write) locks (\fBF_WRLCK\fR), as well as to remove either type of lock (\fBF_UNLCK\fR). \fBF_RDLCK\fR, \fBF_WRLCK\fR and \fBF_UNLCK\fR are defined in <\fBfcntl.h\fR>. If a shared or exclusive lock cannot be set, \fBfcntl()\fR will return immediately with a return value of \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLK64\fR\fR .ad .RS 14n Equivalent to \fBF_OFD_SETLK\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). This command exists solely to allow the use of OFD locks with the transitional 64-bit file interfaces. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLKW\fR\fR .ad .RS 14n This command is the same as \fBF_OFD_SETLK\fR except that if a shared or exclusive lock is blocked by other locks, the process will wait until the request can be satisfied. If a signal that is to be caught is received while \fBfcntl()\fR is waiting for a region, \fBfcntl()\fR will be interrupted. Upon return from the process' signal handler, \fBfcntl()\fR will return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR, and the lock operation will not be done. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLKW64\fR\fR .ad .RS 14n Equivalent to \fBF_OFD_SETLKW\fR, but takes a \fBstruct flock64\fR argument rather than a \fBstruct flock\fR argument. See \fBlf64\fR(7). This command exists solely to allow the use of OFD locks with the transitional 64-bit file interfaces. .RE .sp .LP The following values for \fIcmd\fR are used for file share reservations. A share reservation is placed on an entire file to allow cooperating processes to control access to the file. See the SHARE RESERVATIONS section of this manual page below for additional information. .sp .ne 2 .na \fB\fBF_SHARE\fR\fR .ad .RS 13n Sets a share reservation on a file with the specified access mode and designates which types of access to deny. .RE .sp .ne 2 .na \fB\fBF_UNSHARE\fR\fR .ad .RS 13n Remove an existing share reservation. .RE .SH FILE LOCKING Two types of file locks are supported: POSIX-style and OFD-style. OFD-style locks are associated with the open file description (not descriptor) instead of with a process. Either type is advisory by default, but POSIX-style locks can be mandatory if, and only if, mandatory locking has been enabled on the file being locked. Each type of lock may be created through two different interfaces. POSIX-style locks are created via the \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR commands to this system call or by use of the \fBlockf\fR(3C) routine. There is no difference between locks created via one mechanism or the other. Likewise, OFD-style locks are created via the \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR commands to this system call or by use of the Linux/BSD-compatible \fBflock\fR(3C) routine. Note that this system call supports the creation of range-specified OFD-style file locks, while \fBflock\fR(3C) does not. However, the current implementation of OFD-style locking is limited to locking the entire file. This limitation might be removed in the future. .sp .LP The essential distinction between POSIX-style locks and OFD-style locks lie in how ownership of a lock is scoped. POSIX locks are scoped to a process. All POSIX locks associated with a file for a given process are removed when any file descriptor for that file is closed by that process or the process holding that file descriptor terminates. POSIX-style locks are not inherited by a child process created using \fBfork\fR(2). An OFD-style lock is scoped to the file description for a file, not the process or open file descriptor. Thus all file descriptors referring to the same description (i.e. those created via the \fBF_DUPFD\fR, \fBF_DUP2FD\fR, \fBF_DUPFD_CLOEXEC\fR, or \fBF_DUP2FD_CLOEXEC\fR commands to the \fBfcntl\fR(2) system call, or those created via the \fBdup\fR(2) system call, or those inherited by a child process created via \fBfork\fR(2)) reference the same lock, but a file descriptor obtained via a separate \fBopen\fR(2) call on the same file will reference a different lock. A lock is removed only on the last \fBclose\fR(2) of the description, or when the lock is explicitly unlocked. .sp .LP Locks of both styles are compatible. A file that has been locked with one style of lock will be regarded as locked when creation of a lock of either style is attempted, and information about the lock will be provided via any of the \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR commands to this system call if that lock would conflict with an attempt to create the specified lock regardless of whether the specified lock is of the same style as the conflicting extant lock. Because ownership of OFD-style locks is scoped to the open description rather than the calling process, the \fBl_pid\fR field of a lock descriptor for any such lock will always be set to \fB\(mi1\fR\&. .sp .LP When a shared lock is set on a segment of a file, other callers (regardless of whether in the same or different process and of whether referenced via the same open file) will be able to set shared locks on that segment or a portion of it. A POSIX-style shared lock prevents any other process from setting an exclusive lock on any portion of the protected area. A OFD-style shared lock prevents any caller (even callers in the same process) from setting an exclusive lock on any portion of the protected area, unless the caller makes the request against a file descriptor referencing the same open file against which the shared lock was created, in which case the lock will be downgraded to a shared lock with respect to the specified region. A request for a shared lock of either style will fail if the file descriptor was not opened with read access. .sp .LP A POSIX-style exclusive lock will prevent any other process from setting a shared lock or an exclusive lock (of either style) on any portion of the protected area. A request for an exclusive lock will fail if the file descriptor was not opened with write access. .sp .LP The \fBflock\fR structure contains at least the following elements: .sp .in +2 .nf short l_type; /* lock operation type */ short l_whence; /* lock base indicator */ off_t l_start; /* starting offset from base */ off_t l_len; /* lock length; l_len == 0 means until end of file */ int l_sysid; /* system ID running process holding lock */ pid_t l_pid; /* process ID of process holding lock */ .fi .in -2 .sp .LP The value of \fBl_whence\fR is \fBSEEK_SET\fR, \fBSEEK_CUR\fR, or \fBSEEK_END\fR, to indicate that the relative offset \fBl_start\fR bytes will be measured from the start of the file, current position or end of the file, respectively. The value of \fBl_len\fR is the number of consecutive bytes to be locked. The value of \fBl_len\fR may be negative (where the definition of \fBoff_t\fR permits negative values of \fBl_len\fR). After a successful \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_OFD_GETLK\fR, or \fBF_OFD_GETLK64\fR request, that is, one in which a lock was found, the value of \fBl_whence\fR will be \fBSEEK_SET\fR. .sp .LP The \fBl_pid\fR and \fBl_sysid\fR fields are used only with \fBF_GETLK\fR or \fBF_GETLK64\fR to return the process \fBID\fR of the process holding a POSIX-style blocking lock and to indicate which system is running that process, or \fB\(mi1\fR\& if it is an OFD-style lock. These fields must both be initialized to 0 prior to issuing a OFD-style locking command (\fBF_OFD_GETLK\fR or \fBF_OFD_GETLK64\fR). .sp .LP If \fBl_len\fR is positive, the area affected starts at \fBl_start\fR and ends at \fBl_start\fR + \fBl_len \(mi 1\fR. If \fBl_len\fR is negative, the area affected starts at \fBl_start\fR + \fBl_len\fR and ends at \fBl_start \(mi 1\fR. Locks may start and extend beyond the current end of a file, but must not be negative relative to the beginning of the file. A lock will be set to extend to the largest possible value of the file offset for that file by setting \fBl_len\fR to 0. If such a lock also has \fBl_start\fR set to 0 and \fBl_whence\fR is set to \fBSEEK_SET\fR, the whole file will be locked. .sp .LP If a lock exists for which \fBl_len\fR is 0 and which includes the last byte of the requested segment, and an unlock (\fBF_UNLCK\fR) request is made in which \fBl_len\fR is non-zero and the offset of the last byte of the requested segment is the maximum value for an object of type \fBoff_t\fR, then the \fBF_UNLCK\fR request will be treated as a request to unlock from the start of the requested segment with an \fBl_len\fR equal to 0. Otherwise, the request will attempt to unlock only the requested segment. .sp .LP There will be at most one type of lock set for each byte in the file. Before a successful return from an \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request when the calling process has previously existing POSIX-style locks on bytes in the region specified by the request, the previous POSIX-style lock type for each byte in the specified region will be replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, an \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR request will (respectively) fail or block when locks exist on bytes in the specified region and the type of any of those locks conflicts with the type specified in the request. .sp .LP Similarly, before a successful return from an \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR request when previously-created OFD-style locks associated with the open file apply to bytes in the region specified by the request, the previous OFD-style lock type for each byte in the specified region will be replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, an \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR request will (respectively) fail or block when locks exist on bytes in the specified region and the type of any of those locks conflicts with the type specified in the request. .sp .LP A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock another process' locked region. If the system detects that sleeping until a locked region is unlocked would cause a deadlock, \fBfcntl()\fR will fail with an \fBEDEADLK\fR error. This deadlock detection and error value apply only to POSIX-style locks. No deadlock detection is performed when attempting to set an OFD-style lock. .SH SHARE RESERVATIONS File share reservations are an advisory form of access control among cooperating processes, on both local and remote machines. They are most often used by \fBDOS\fR or Windows emulators and \fBDOS based\fR \fBNFS\fR clients. However, native UNIX versions of \fBDOS\fR or Windows applications may also choose to use this form of access control. .sp .LP A share reservation is described by an \fBfshare\fR structure defined in <\fBsys/fcntl.h\fR>, which is included in <\fBfcntl.h\fR> as follows: .sp .in +2 .nf typedef struct fshare { short f_access; short f_deny; int f_id; } fshare_t; .fi .in -2 .sp .LP A share reservation specifies the type of access, \fBf_access\fR, to be requested on the open file descriptor. If access is granted, it further specifies what type of access to deny other processes, \fBf_deny\fR. A single process on the same file may hold multiple non-conflicting reservations by specifying an identifier, \fBf_id\fR, unique to the process, with each request. .sp .LP An \fBF_UNSHARE\fR request releases the reservation with the specified \fBf_id\fR. The \fBf_access\fR and \fBf_deny\fR fields are ignored. .sp .LP Valid \fBf_access\fR values are: .sp .ne 2 .na \fB\fBF_RDACC\fR\fR .ad .RS 11n Set a file share reservation for read-only access. .RE .sp .ne 2 .na \fB\fBF_WRACC\fR\fR .ad .RS 11n Set a file share reservation for write-only access. .RE .sp .ne 2 .na \fB\fBF_RWACC\fR\fR .ad .RS 11n Set a file share reservation for read and write access. .RE .sp .LP Valid \fBf_deny\fR values are: .sp .ne 2 .na \fB\fBF_COMPAT\fR\fR .ad .RS 12n Set a file share reservation to compatibility mode. .RE .sp .ne 2 .na \fB\fBF_RDDNY\fR\fR .ad .RS 12n Set a file share reservation to deny read access to other processes. .RE .sp .ne 2 .na \fB\fBF_WRDNY\fR\fR .ad .RS 12n Set a file share reservation to deny write access to other processes. .RE .sp .ne 2 .na \fB\fBF_RWDNY\fR\fR .ad .RS 12n Set a file share reservation to deny read and write access to other processes. .RE .sp .ne 2 .na \fB\fBF_NODNY\fR\fR .ad .RS 12n Do not deny read or write access to any other process. .RE .SH RETURN VALUES Upon successful completion, the value returned depends on \fIcmd\fR as follows: .sp .ne 2 .na \fB\fBF_DUPFD\fR\fR .ad .RS 14n A new file descriptor. .RE .sp .ne 2 .na \fB\fBF_FREESP\fR\fR .ad .RS 14n Value of \fB0\fR. .RE .sp .ne 2 .na \fB\fBF_GETFD\fR\fR .ad .RS 14n Value of flags defined in \fB\fR\&. The return value will not be negative. .RE .sp .ne 2 .na \fB\fBF_GETFL\fR\fR .ad .RS 14n Value of file status flags and access modes. The return value will not be negative. .RE .sp .ne 2 .na \fB\fBF_GETLK\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_GETLK64\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_GETOWN\fR\fR .ad .RS 14n Value of the socket owner process or process group; this will not be \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_GETXFL\fR\fR .ad .RS 14n Value of file status flags, access modes, and creation and assignment flags. The return value will not be negative. .RE .sp .ne 2 .na \fB\fBF_OFD_GETLK\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_GETLK64\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLK\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLK64\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLKW\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_OFD_SETLKW64\fR\fR .ad .RS 14n Value other then \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETFD\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETFL\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETLK\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETLK64\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETLKW\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETLKW64\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SETOWN\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_SHARE\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .ne 2 .na \fB\fBF_UNSHARE\fR\fR .ad .RS 14n Value other than \fB\(mi1\fR\&. .RE .sp .LP Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error. .SH ERRORS The \fBfcntl()\fR function will fail if: .sp .ne 2 .na \fB\fBEAGAIN\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLK64\fR, the type of lock \fB(l_type)\fR is a shared (\fBF_RDLCK\fR) or exclusive (\fBF_WRLCK\fR) lock, and the segment of a file to be locked is already exclusive-locked by another process or open file; or the type is an exclusive lock and some portion of the segment of a file to be locked is already shared-locked or exclusive-locked by another process or open file. .sp The \fIcmd\fR argument is \fBF_FREESP\fR, the file exists, mandatory file/record locking is set, and there are outstanding record locks on the file; or the \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, or \fBF_SETLKW64\fR, mandatory file/record locking is set, and the file is currently being mapped to virtual memory using \fBmmap\fR(2). .sp The \fIcmd\fR argument is \fBF_SHARE\fR and \fBf_access\fR conflicts with an existing \fBf_deny\fR share reservation. .RE .sp .ne 2 .na \fB\fBEBADF\fR\fR .ad .RS 13n The \fIfildes\fR argument is not a valid open file descriptor; or the \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, the type of lock, \fBl_type\fR, is a shared lock (\fBF_RDLCK\fR), and \fIfildes\fR is not a valid file descriptor open for reading; or the type of lock \fBl_type\fR is an exclusive lock (\fBF_WRLCK\fR) and \fIfildes\fR is not a valid file descriptor open for writing. .sp The \fIcmd\fR argument is \fBF_FREESP\fR and \fIfildes\fR is not a valid file descriptor open for writing. .sp The \fIcmd\fR argument is \fBF_DUP2FD\fR, and \fIarg\fR is negative or is not less than the current resource limit for \fBRLIMIT_NOFILE.\fR .sp The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation is for write access, and \fIfildes\fR is not a valid file descriptor open for writing. .sp The \fIcmd\fR argument is \fBF_SHARE,\fR the \fBf_access\fR share reservation is for read access, and \fIfildes\fR is not a valid file descriptor open for reading. .RE .sp .ne 2 .na \fB\fBEFAULT\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, \fBF_OFD_SETLKW64\fR, \fBF_SHARE\fR, \fBF_UNSHARE\fR, or \fBF_FREESP\fR and the \fIarg\fR argument points to an illegal address. .RE .sp .ne 2 .na \fB\fBEINTR\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the function was interrupted by a signal. .RE .sp .ne 2 .na \fB\fBEINVAL\fR\fR .ad .RS 13n The \fIcmd\fR argument is invalid or not supported by the file system; or the \fIcmd\fR argument is \fBF_DUPFD\fR and \fIarg\fR is negative or greater than or equal to \fBOPEN_MAX\fR; or the \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_GETLK64\fR, \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and the data pointed to by \fIarg\fR is not valid; or \fIfildes\fR refers to a file that does not support locking. .sp The \fIcmd\fR argument is \fBF_UNSHARE\fR and a reservation with this \fBf_id\fR for this process does not exist. .sp The \fIcmd\fR argument is \fBF_DUP2FD_CLOEXEC\fR and \fIfildes\fR is equal to \fBarg\fR. .RE .sp .ne 2 .na \fB\fBEIO\fR\fR .ad .RS 13n An I/O error occurred while reading from or writing to the file system. .RE .sp .ne 2 .na \fB\fBEMFILE\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBF_DUPFD\fR and either \fBOPEN_MAX\fR file descriptors are currently open in the calling process, or no file descriptors greater than or equal to \fIarg\fR are available. .RE .sp .ne 2 .na \fB\fBENOLCK\fR\fR .ad .RS 13n The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR, and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit. .RE .sp .ne 2 .na \fB\fBENOLINK\fR\fR .ad .RS 13n Either the \fIfildes\fR argument is on a remote machine and the link to that machine is no longer active; or the \fIcmd\fR argument is \fBF_FREESP\fR, the file is on a remote machine, and the link to that machine is no longer active. .RE .sp .ne 2 .na \fB\fBEOVERFLOW\fR\fR .ad .RS 13n One of the values to be returned cannot be represented correctly. .sp The \fIcmd\fR argument is \fBF_GETLK\fR, \fBF_SETLK\fR, \fBF_SETLKW\fR, \fBF_OFD_GETLK\fR, \fBF_OFD_SETLK\fR, or \fBF_OFD_SETLKW\fR, and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of type \fBoff_t\fR. .sp The \fIcmd\fR argument is \fBF_GETLK64\fR, \fBF_SETLK64\fR, \fBF_SETLKW64\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK64\fR, or \fBF_OFD_SETLKW64\fR, and the smallest or, if \fBl_len\fR is non-zero, the largest, offset of any byte in the requested segment cannot be represented correctly in an object of type \fBoff64_t\fR. .RE .sp .LP The \fBfcntl()\fR function may fail if: .sp .ne 2 .na \fB\fBEAGAIN\fR\fR .ad .RS 11n The \fIcmd\fR argument is \fBF_SETLK\fR, \fBF_SETLK64\fR, \fBF_SETLKW\fR, \fBF_SETLKW64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR and the file is currently being mapped to virtual memory using \fBmmap\fR(2). .RE .sp .ne 2 .na \fB\fBEDEADLK\fR\fR .ad .RS 11n The \fIcmd\fR argument is \fBF_SETLKW\fR or \fBF_SETLKW64\fR, the lock is blocked by some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a deadlock. .sp The \fIcmd\fR argument is \fBF_FREESP,\fR mandatory record locking is enabled, \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear and a deadlock condition was detected. .RE .sp .ne 2 .na \fB\fBEOPNOTSUPP\fR .ad .RS 11n The \fIcmd\fR argument is \fBF_OFD_GETLK\fR, \fBF_OFD_GETLK64\fR, \fBF_OFD_SETLK\fR, \fBF_OFD_SETLK64\fR, \fBF_OFD_SETLKW\fR, or \fBF_OFD_SETLKW64\fR and the locking of files of the type indicated by the \fIfildes\fR argument is not supported. .RE .SH ATTRIBUTES See \fBattributes\fR(7) for descriptions of the following attributes: .sp .sp .TS box; c | c l | l . ATTRIBUTE TYPE ATTRIBUTE VALUE _ Interface Stability Standard _ MT-Level Async-Signal Safe .TE .SH SEE ALSO .BR chmod (2), .BR close (2), .BR creat (2), .BR dup (2), .BR exec (2), .BR fork (2), .BR mmap (2), .BR open (2), .BR pipe (2), .BR read (2), .BR sigaction (2), .BR write (2), .BR dup2 (3C), .BR flock (3C), .BR lockf (3C), .BR fcntl.h (3HEAD), .BR attributes (7), .BR lf64 (7), .BR standards (7), .BR lockd (8) .sp .LP \fIProgramming Interfaces Guide\fR .SH NOTES In the past, the variable \fBerrno\fR was set to \fBEACCES\fR rather than \fBEAGAIN\fR when a section of a file is already locked by another process. Therefore, portable application programs should expect and test for either value. .sp .LP Advisory locks allow cooperating processes to perform consistent operations on files, but do not guarantee exclusive access. Files can be accessed without advisory locks, but inconsistencies may result. The network share locking protocol does not support the \fBf_deny\fR value of \fBF_COMPAT\fR. For network file systems, if \fBf_access\fR is \fBF_RDACC\fR, \fBf_deny\fR is mapped to \fBF_RDDNY\fR. Otherwise, it is mapped to \fBF_RWDNY\fR. .sp .LP To prevent possible file corruption, the system may reject \fBmmap()\fR requests for advisory locked files, or it may reject advisory locking requests for mapped files. Applications that require a file be both locked and mapped should lock the entire file (\fBl_start\fR and \fBl_len\fR both set to 0). If a file is mapped, the system may reject an unlock request, resulting in a lock that does not cover the entire file. .sp .LP The process ID returned for locked files on network file systems might not be meaningful. .sp .LP If the file server crashes and has to be rebooted, the lock manager (see \fBlockd\fR(8)) attempts to recover all locks that were associated with that server. If a lock cannot be reclaimed, the process that held the lock is issued a \fBSIGLOST\fR signal.