FCNTL(2-SVR3) RISC/os Reference Manual FCNTL(2-SVR3)
NAME
fcntl - file control
SYNOPSIS
#include <bsd/sys/types.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,
fcntl, or pipe system call.
The commands available are:
F_DUPFD Return 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(2)
system calls.
F_GETFD Get 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_SETFD Set the close-on-exec flag associated with fildes
to the low-order bit of arg (0 or 1 as above).
F_GETFL Get file status flags.
F_SETFL Set file status flags to arg. Only certain flags
can be set [see fcntl(5)].
F_GETLK Get the first lock which blocks the lock descrip-
tion given by the variable of type struct flock
pointed to by arg. The information retrieved
Printed 11/19/92 Page 1
FCNTL(2-SVR3) RISC/os Reference Manual FCNTL(2-SVR3)
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 estab-
lish 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
immediately 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 segment 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.
The structure flock describes the type (l_type), starting
offset (l_whence), relative offset (l_start), size (l_len),
process id (l_pid), and RFS system id (l_sysid) of the seg-
ment of the file to be affected. 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 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 seg-
ment 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 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.
Page 2 Printed 11/19/92
FCNTL(2-SVR3) RISC/os Reference Manual FCNTL(2-SVR3)
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.
ERRORS
fcntl will fail if one or more of the following are true:
[EBADF] fildes is not a valid open file descriptor.
[EINVAL] cmd is F_DUPFD. arg is either negative, or greater
than or equal to the configured value for the max-
imum 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 seg-
ment 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 putting the calling-
process to sleep, waiting for that lock to become
free, would cause a deadlock.
[EFAULT] cmd is F_SETLK, arg points outside the program
address space.
[EINTR] A signal was caught during the fcntl system call.
[ENOLINK]
fildes is on a remote machine and the link to that
machine is no longer active.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2),
pipe(2), proc(4), fcntl(5).
DIAGNOSTICS
Upon successful completion, the value returned depends on
cmd as follows:
Printed 11/19/92 Page 3
FCNTL(2-SVR3) RISC/os Reference Manual FCNTL(2-SVR3)
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.
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.
WARNINGS
Because 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, portable application pro-
grams should expect and test for either value.
Page 4 Printed 11/19/92