FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
-------------------------------------------------------------------------------
fcntl, flock, lockf
PURPOSE
Controls open file and socket descriptors.
SYNTAX
#include <unistd.h>
int (lockf, (d, cmd, arg)
int d, cmd, arg;
DESCRIPTION
The fcntl system call performs controlling operations on the open file or
socket specified by the d parameter.
The d parameter is an open file descriptor obtained from a creat, open, dup,
fcntl, or pipe system call, or a socket descriptor from a socket or socketpair
system call. The arg parameter is a variable that depends on the value of the
cmd parameter.
The following cmds get a descriptor or associated flags or set those flags:
F_DUPFD Returns a new descriptor as follows:
o Lowest numbered available descriptor greater than or equal to arg
o Same object reference as the original descriptor
o Same file pointer as the original file (that is, both file
descriptors share one file pointer)
o Same access mode (read, write or read/write)
o Same locks
o Same file status flags (that is, both file descriptors share the
same file status flags)
o The close-on-exec flag associated with the new descriptor is set
to remain open across exec system calls.
F_GETFD Gets the flags of the descriptor d.
F_SETFD Sets the close-on-exec flag associated with the d parameter to the
value of the low-order bit of arg (0 or 1 as for F_GETFD).
Processed November 7, 1990 FCNTL(2,L) 1
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
F_GETFL Gets the file status flags of the file descriptor d.
F_SETFL Sets the file status flags to the value of the arg parameter. Only
the flags O_NDELAY, O_NONBLOCK, O_APPEND, and O_ASYNC can be set. If
you attempt to set any other flags with F_SETFL, the fcntl system
call does not set the flags and returns without an error message.
O_ASYNC enables the SIGIO signal to be sent to the process or process
group specified by the F_SETOWN when I/O is possible.
F_GETOWN Gets the process ID or process group ID set to receive SIGIO and
SIGURG signals; process group IDs are returned as negative values.
F_SETOWN Sets the process ID or process group ID to receive SIGIO and SIGURG
signals. A process group ID is specified by giving arg as a negative
value; a positive value is a process ID.
When using the file locking and unlocking cmds (F_GETLK, F_SETLK, and
F_SETLKW), the arg parameter is a pointer to a structure of type flock. The
flock structure pointed to by the arg parameter describes the lock and is
defined in the fcntl.h header file. It contains the following members:
short l_type; /* F_RDLCK, F_WRLCK, F_UNLCK */
short l_whence; /* flag for starting offset */
long l_start; /* relative offset in bytes */
long l_len; /* if 0 then until EOF */
unsigned long l_sysid; /* node ID */
pid_t l_pid; /* returned with F_GETLK */
l_type Describes the type of lock. Possible values are F_RDLCK, F_WRLCK, and
F_UNLCK.
l_whence
Defines the starting point of the relative offset, l_start. A value of
0 indicates the start of the file, 1 selects the current position, and
2 indicates the end of the file.
l_start Defines the relative offset in bytes, measured from the starting point
in l_whence.
l_len Specifies the number of consecutive bytes to be locked.
l_sysid Contains the ID of the node that already has a lock placed on the area
defined by the fcntl system call. This field is returned only when the
F_GETLK cmd is used.
l_pid Contains the ID of a process that already has a lock placed on the area
defined by the fcntl system call. This field is returned only when the
F_GETLK cmd is used.
The following cmds use the flock structure and perform operations associated
with file locks:
Processed November 7, 1990 FCNTL(2,L) 2
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
F_GETLK Gets the first lock that blocks the lock described in the flock
structure pointed to by arg. If a lock is found, the retrieved
information overwrites the information in this structure. If no lock
is found that would prevent this lock from being created, then the
structure is passed back unchanged except that the lock type is set
to F_UNLCK.
F_SETLK Sets or clears a file lock according to the flock structure pointed
to by arg. F_SETLK is used to establish read (F_RDLCK) and write
(F_WRLCK) locks, as well as to remove either type of lock (F_UNLCK).
F_RDLCK, F_WRLCK, and F_UNLCK are defined by the fcntl.h header file.
If a read or write lock cannot be set, fcntl returns immediately with
an error value of -1.
F_SETLKW Works like F_SETLK except that if a read or write lock is blocked by
existing locks, the process sleeps until the section of the file is
free to be locked.
When a read lock has been set on a section of a file, other processes may also
set read locks on that section or subsets of it. A read lock prevents any
other process from setting a write lock on any part of the protected area. The
file descriptor on which a read lock is being placed must have been opened with
read access.
A write lock prevents any other process from setting a read lock or a write
lock on any part of the protected area. Only one write lock and no read locks
may exist for a specific section of a file at any time. The file descriptor on
which a write lock is being placed must have been opened with write access.
Locks may start and extend beyond the current end of a file but may not be
negative relative to the beginning of the file. A lock may be set to extend to
the end of the file by setting l_len to 0. If such a lock also has l_start and
l_whence set to 0, the whole file is locked.
Some general rules about file locking include:
o Changing or unlocking part of a file in the middle of a locked section
leaves two smaller sections locked at each end of the originally locked
section.
o When the calling process holds a lock on a file, that lock is replaced by
later calls to fcntl.
o All locks associated with a file for a given process are removed when a
file descriptor for that file is closed by the process or the process
holding the file descriptor ends.
o Locks are not inherited by a child process after executing a fork system
call.
If the Transparent Computing Facility is installed, the following also applies
to use of fcntl:
Processed November 7, 1990 FCNTL(2,L) 3
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
o If the file being locked is a replicated file, the primary copy must be
available, even if the file is open for read and another copy can otherwise
still be used. This restriction is necessary to guarantee that no two
processes on sites in different network partitions hold conflicting locks
on the same file at the same time.
o The loss of the site storing the file (storing the primary copy, if the
file is replicated) causes a process that holds locks on the file to lose
those locks. If not caught or ignored, this signal causes the process to
be terminated.
Notes:
1. In addition to fcntl, the lockf system call can also be used to set write
(exclusive) locks.
2. Deadlocks due to file locks in a distributed system are not always
detected. When such deadlocks are possible, the programs requesting the
locks should set timeout timers.
COMPATIBILITY INTERFACES
The following additional interfaces are provided:
o lockf (fildes, F_LOCK, size) is equivalent to fcntl (fildes, F_SETLKW,
flock) where flock has:
l_type = F_WRLCK
l_whence = 1
l_start = (size >= 0) ? 0 : size
l_len = (size >= 0) ? size : -size;
o lockf (fildes, F_TLOCK, size) is equivalent to fcntl (fildes, F_SETLK,
flock ) where flock is as for F_LOCK:
l_type = F_WRLCK
l_whence = 1
l_start = (size >= 0) ? 0 : size
l_len = (size >= 0) ? size : -size;
o lockf (fildes, F_ULOCK, size) is equivalent to fcntl (fildes, F_SETLK,
flock ) where flock is as for F_LOCK, except l_type is F_UNLCK:
l_type = F_UNLCK
l_whence = 1
l_start = (size >= 0) ? 0 : size
l_len = (size >= 0) ? size : -size;
o lockf (fildes, F_TEST, size) is equivalent to fcntl (fildes, F_GETLCK,
flock) where flock is as for F_LOCK:
Processed November 7, 1990 FCNTL(2,L) 4
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
l_whence = 1
l_start = (size >= 0) ? 0 : size
l_len = (size >= 0) ? size : -size;
except that the return value is established as:
- if no conflicting lock exists, lockf returns 0.
- if a conflicting lock exists, lockf returns -1 and sets errno to
EAGAIN.
The commands, F_LOCK, F_TLOCK, F_ULOCK, and F_TEST are defined in
<sys/lockf.h>.
o For 4.3BSD compatibility, the flock interface is also supported. To use
flock, compile with the Berkeley Compatibility Library (libbsd.a).
flock (fd, operation)
where operation is the inclusive OR of LOCK_SH, LOCK_EX and, possibly,
LOCK_NB, or LOCK_UN, is equivalent to fcntl (fildes, cmd, flock)
where cmd is F_SETLK (or, F_SETLKW if LOCK_NB is set) and flock is set
follows:
l_type = F_RDLCK if LOCK_SH.
l_type = F_WRLCK if LOCK_EX.
l_type = F_UNLCK if LOCK_UN.
l_whence = 0
l_start = 0
l_len = 0
RETURN VALUE
Upon successful completion, the value returned depends on the value of the cmd
parameter as follows:
cmd Return Value
F_DUPFD A new descriptor
F_GETFD The value of the flag (only the low-order bit is
defined)
F_GETLK A value other than -1
F_SETFD A value other than -1
F_GETFL The value of file flags
F_SETFL A value other than -1
F_SETLK A value other than -1
F_SETLKW A value other than -1
F_GETOWN A process ID or a negative process group ID. Process
group IDs are never 1
F_SETOWN A value other than -1.
If the fcntl system call fails, a value of -1 is returned, and errno is set to
indicate the error.
Processed November 7, 1990 FCNTL(2,L) 5
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
ERROR CONDITIONS
The fcntl system call fails if one or more of the following are true:
EBADF The d parameter is not a valid open file descriptor.
EBADF A read lock (F_RDLCK) is attempted on a file open only for writing
(O_WRONLY) or a write lock (F_WRLCK) is attempted on a file open only
for reading (O_RDONLY).
EMFILE The cmd parameter is F_DUPFD and 200 file descriptors are currently
open.
EACCES The cmd parameter is F_SETLK, the l_type parameter is F_RDLCK, and
the segment of the file to be locked is already write-locked by
another process.
EACCES The cmd parameter is F_SETLK, the l_type parameter is F_WRLCK, and
the segment of a file to be locked is already read-locked or
write-locked by another process.
Note: Because in the future errno may be set to EAGAIN rather than
to EACCES for the two errors described above, programs should
expect and test for both values.
EDEADLK The cmd parameter is F_SETLKW, the lock is blocked by some lock from
another process. Putting the calling process to sleep while waiting
for that lock to become free would cause a deadlock.
ENOLCK The cmd parameter is F_SETLK or F_SETLKW, the type of lock is F_RDLCK
or F_WRLCK, and there are no more file locks available. (Too many
segments are already locked.)
EINVAL The cmd parameter is F_GETLK, F_SETLK, or F_SETLKW and the arg
parameter or the data it points to is not valid.
EINVAL The cmd parameter is F_DUPFD and the arg parameter is negative or
greater than 199.
If the Transparent Computing Facility is installed on your system, fcntl can
also fail if one or more of the following are true:
ESITEDN1 The site which stores this file is now or has been down.
ESITEDN2 The operation was terminated because a site failed.
ETXTBSY An attempt was made to lock a region of a file which is currently
being executed. This error is only for replicated files and only in
situations where obtaining a lock at the primary copy of a replicated
file system would interfere with processes which are currently
executing this program.
Processed November 7, 1990 FCNTL(2,L) 6
FCNTL(2,L) AIX Technical Reference FCNTL(2,L)
ENOSTORE An attempt was made to lock a replicated file which has already been
deleted.
EROFS A lock is requested for a file in a replicated file system in which
the primary copy is unavailable.
ENFILE The system inode table at the current synchronization site is full.
RELATED INFORMATION
In this book: "close, closex," "exec: execl, execv, execle, execve, execlp,
execvp," "fcntl, flock, lockf," "open, openx, creat," and "fcntl.h."
Processed November 7, 1990 FCNTL(2,L) 7