FCNTL(2-POSIX) RISC/os Reference Manual FCNTL(2-POSIX)
NAME
fcntl - file control
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
int fcntl (fildes, cmd, arg)
int fildes, cmd, arg;
DESCRIPTION
fcntl provides for control over open files. fildes is an
open file descriptor obtained from a creat, open, dup, dup2,
fcntl, or pipe system call.
The commands available are:
F_DUPFD Return a new file descriptor as follows:
Lowest numbered available (i.e., not already
open) file descriptor greater than or equal
to arg.
Same open file description as the original
file. (i.e., both file descriptors share one
file description).
Same access mode (read, write or read/write).
Same file status flags (i.e., both file
descriptors share the same file status
flags).
The FD_CLOEXEC flag associated with the new
file descriptor is cleared to keep the file
open across exec(2) system calls.
F_GETFD Get the file descriptor flags associated with
the file descriptor fildes. File descriptor
flags are associated with a single file
descriptor and do no affect other file
descriptors that refer to the same file. If
the FD_CLOEXEC flag is clear in arg, the file
will remain open across calls to exec(2)
functions, otherwise the file will be closed
upon successful execution of an exec(2) func-
tion.
F_SETFD Set the file descriptor flags associated with
fildes to arg. arg is interpreted as an int.
If the FD_CLOEXEC flag is clear in arg, the
Printed 1/15/91 Page 1
FCNTL(2-POSIX) RISC/os Reference Manual FCNTL(2-POSIX)
file will remain open across calls to exec(2)
functions, otherwise the file will be closed
upon successful execution of an exec(2) func-
tion.
F_GETFL Get file status flags, and file access modes
for the open file description associated with
fildes. File status flags are associated
with a single file descriptor and do not
affect other file descriptors that refer to
the same file.
F_SETFL Set file status flags to arg. Only certain
flags can be set [see fcntl(5)]. The file
access mode bits cannot be modified by fcntl.
F_GETLK Get the first lock which blocks the lock
description given by the variable of type
struct flock pointed to by arg. The informa-
tion 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_SETLK Set or clear a file segment lock according to
the variable of type struct flock pointed to
by arg [see fcntl(5)]. The cmd F_SETLK 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 return immedi-
ately with an error value of -1.
F_SETLKW This cmd 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 seg-
ment is free to be locked.
A read lock prevents any process from write locking the pro-
tected 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.
Page 2 Printed 1/15/91
FCNTL(2-POSIX) RISC/os Reference Manual FCNTL(2-POSIX)
The structure flock, defined in <fcntl.h>, describes an
advisory lock. It includes the following members:
short l_type F_RDLCK, F_WRLCK, or F_UNLCK.
short l_whence Flag for starting offset.
off_t l_start relative offset in bytes.
off_t l_len size; if 0, then until EOF.
pid_t l_pid process id of the process holding the lock.
The value of l_whence is SEEK_SET, SEEK_CUR, or SEEK_END to
indicate that the relative offset, l_start bytes, will be
measured from the start of the file, current position, or
end of the file, respectively. The value of l_len is the
number of consecutive bytes to be locked. If l_len is nega-
tive, l_len is set to its absolute value and l_start is
decremented by this value. The l_pid field is only used
with F_GETLK to return the process ID of the process holding
a blocking lock. After a successful F_GETLK request, the
value of l_whence is SEEK_SET. The process id and system id
fields are used only with the F_GETLK cmd to return the
values 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_whence set to SEEK_SET and 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 pro-
cess causes the old lock type to be removed and the new lock
type to take effect. 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(2) system call.
When mandatory file and record locking is active on a file,
[see chmod(2)], read and write system calls issued on the
file will be affected by the record locks in effect.
RETURN VALUES
Upon successful completion, the value returned depends on
cmd as follows:
F_DUPFD A new file descriptor.
F_GETFD Value of flag (only the low-order bit is defined).
F_SETFD Value other than -1.
F_GETFL Value of file flags.
F_SETFL Value other than -1.
Printed 1/15/91 Page 3
FCNTL(2-POSIX) RISC/os Reference Manual FCNTL(2-POSIX)
F_GETLK Value other than -1.
F_SETLK Value other than -1.
F_SETLKW Value other than -1.
Otherwise, a value of -1 is returned and errno is set to
indicate the error.
ERRORS
fcntl will fail if one or more of the following are true:
[EBADF] fildes is not a valid open file descrip-
tor, cmd is F_SETLK or F_SETLKW, the
type of lock is a shared lock (l_type is
F_RDLCK) , and fildes is not a valid
file descriptor open for reading, or cmd
is F_SETLK or F_SETLKW, the type of lock
is an exclusive lock (l_type is
F_WRLCK), and fildes is not a valid file
descriptor open for writing.
[EINVAL] cmd is F_DUPFD. arg is either negative,
or greater than or equal to the config-
ured value for the maximum number of
open file descriptors allowed each user.
[EINVAL] cmd is F_GETLK, F_SETLK, or SETLKW and
arg or the data it points to is not
valid.
[EACCES] cmd is F_SETLK the type of lock (l_type)
is a read (F_RDLCK) lock and the segment
of a file to be locked is already write
locked by another process or the type is
a write (F_WRLCK) lock and the segment
of a file to be locked is already read
or write locked by another process.
[ENOLCK] cmd is F_SETLK or F_SETLKW, the type of
lock is a read or write lock, and there
are no more record locks available (too
many file segments locked) because the
system maximum has been exceeded.
[EDEADLK] cmd is F_SETLKW, the lock is blocked by
some lock from another process, and put-
ting the calling process to sleep, wait-
ing for that lock to become free, would
cause a deadlock.
[EFAULT] cmd is F_SETLK, arg points outside the
program address space.
Page 4 Printed 1/15/91
FCNTL(2-POSIX) RISC/os Reference Manual FCNTL(2-POSIX)
[EMFILE] cmd is F_DUPFD and {OPEN_MAX} file
descriptors are currently in use by this
process, or no file descriptors greater
than or equal to arg are available.
[EINTR] A signal was caught during the fcntl
system call.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2),
pipe(2), fcntl(5).
WARNINGS
In the future the variable errno will be set to EAGAIN
rather than EACCES when a section of a file is already
locked by another process.
Printed 1/15/91 Page 5