FCNTL(S) XENIX System V FCNTL(S)
Name
fcntl - Controls open files.
Syntax
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd;
Description
fcntl provides for control over open files. fildes is an
open file descriptor obtained from a creat, open, dup,
fcntl, or pipe system call. arg is either an int or a
pointer , depending on the cmd given. See below.
The cmds available are:
F_DUPFDReturns a new file descriptor as follows:
Lowest numbered available file descriptor greater
than or equal to arg.
Same open file (or pipe) as the original file.
Same file pointer as the original file (i.e., both
file descriptors share one file pointer).
Same access mode (read, write or read/write).
Same file status flags (i.e., both file descriptors
share the same file status flags).
The close-on-exec flag associated with the new file
descriptor is set to remain open across exec(S)
system calls.
F_GETFDGets the close-on-exec flag associated with the file
descriptor fildes. If the low-order bit is 0 the
file will remain open across exec, otherwise the file
will be closed upon execution of exec.
F_SETFDSets the close-on-exec flag associated with fildes to
the low-order bit of arg (0 or otherwise as above).
F_GETFLGets file status flags: O_RDONLY, O_WRONLY, O_RDWR,
O_NDELAY, or O_APPEND.
F_SETFLSets file status flags to arg. Only certain flags
can be set.
F_GETLKGets the first lock which blocks the lock description
given by the variable of type struct flock pointed to
Page 1 (printed 8/7/87)
FCNTL(S) XENIX System V FCNTL(S)
by arg (see below). The information retrieved
overwrites the information passed to fcntl in the
flock structure. If no lock is found that would
prevent this lock from being created, then the
structure is passed back unchanged except for the
lock type which will be set to F_UNLCK.
F_SETLKSets or clears a file segment lock according to the
variable of type struct flock pointed to by arg (see
below). The F_SETLK command is used to establish
read (F_RDLCK) and write (F_WRLCK) locks, as well as
remove either type of lock (F_UNLCK). If a read or
write lock cannot be set, fcntl will immediately
return an error value of - 1.
F_SETLKW
This command is the same as F_SETLK except that if a
read or write lock is blocked by other locks, the
process will sleep until the segment is free to be
locked.
A read lock prevents any process from write locking the
protected area. More than one read lock may exist for a
given segment of a file at a given time. The file
descriptor on which a read lock is being placed must have
been opened with read access.
A write lock prevents any process from read locking or write
locking the protected area. Only one write lock may exist
for a given segment of a file at a given time. The file
descriptor on which a write lock is being placed must have
been opened with write access.
The structure flock describes the type (l_type), starting
offset (l_whence), relative offset (l_start), size (l_len),
process ID (l_pid) and system ID (l_sysid) of the segment of
the file to be affected as shown below:
struct flock {
short l_type: /* F_RDLCK, F_WRLCK, F_UNLCK*/
short l_whence: /* flag to choose starting offset */
long l_start: /* relative offset in bytes */
long l_len: /* if 0 then until EOF */
short l_pid: /* returned with F_GETLK */
short l_sysid: /* returned with F_GETLK */
};
l_whence is 0,1 or 2 to indicate that the relative offset
will be measured from the start of the file, current
position or end of the file, respectively.
The process ID and system ID fields are only used with the
Page 2 (printed 8/7/87)
FCNTL(S) XENIX System V FCNTL(S)
F_GETLK command to return the value for a blocking lock.
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 always extend to the end of file
by setting l_len to zero (0). If such a lock also has
l_start set to zero (0), the whole file will be locked.
Changing or unlocking a segment from the middle of a larger
locked segment leaves two smaller segments for either end.
Locking a segment that is already locked by the calling
process causes the old lock type to be removed and the new
lock type to take affect. All locks associated with a file
for a given process are removed when a file descriptor for
that file is closed by that process or the process holding
that file descriptor terminates. Locks are not inherited by
a child process in a fork(S) system call.
fcntl fails if one or more of the following is true:
fildes is not a valid open file descriptor. [EBADF]
cmd is F_DUPFD and 60 file descriptors are currently
open. [EMFILE]
cmd is F_DUPFD and arg is negative or greater than 60.
[EINVAL]
cmd is F_GETLK, F_SETLK, or F_SETLKW and arg or the
data it points to is not valid. [EINVAL]
cmd is F_SETLK, the type of lock (l_type) is a read
(F_RDLCK) or write (F_WRLCK) lock and the segment of a
file to be locked is by another process or the type is
a write lock and the segment of a file to be locked is
already read or write locked by another process.
[EAGAIN]
cmd is F_SETLK or F_SETLKW, the type of lock is a read
or write lock and there are no more file locks
available (too many segments are locked). [ENOLOCK]
cmd is F_SETLK, the lock is blocked by a lock from
another process and putting the calling process to
sleep or waiting for that lock to become free, would
cause a deadlock. [EDEADLK] or [EDEADLOCK]
Page 3 (printed 8/7/87)
FCNTL(S) XENIX System V FCNTL(S)
Return Value
Upon successful completion, the value returned depends on
cmd as follows:
F_DUPFDA new file descriptor
F_GETFDValue of flag (only the low-order bit is
defined)
F_SETFDValue other than -1
F_GETFLValue of file flags
F_SETFLValue other than -1
F_GETLKValue other than -1
F_SETLKValue other than -1
F_SETLKW
Value other than -1
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
See Also
close(S), exec(S), lockf(S), open(S)
Notes
fcntl provides mandatory record locking.
Page 4 (printed 8/7/87)