FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
NAME
fcntl - file control
SYNOPSIS
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl (int fildes, int cmd, ... /* arg */);
DESCRIPTION
fcntl provides for control over open files. fildes is an
open file descriptor [see intro(2)].
fcntl may take a third argument, arg, whose data type, value
and use depend upon the value of cmd. cmd specifies the
operation to be performed by fcntl and may be one of the
following:
F_DUPFD Return a new file descriptor with the follow-
ing characteristics:
Lowest numbered available file descriptor
greater than or equal to the integer value
given as the third argument.
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) as the original file.
Shares any locks associated with the ori-
ginal file descriptor.
Same file status flags (i.e., both file
descriptors share the same file status
flags) as the original file.
The close-on-exec flag [see F_GETFD] asso-
ciated 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
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.
Printed 11/19/92 Page 1
FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
F_SETFD Set the close-on-exec flag associated with
fildes to the low-order bit of the integer
value given as the third argument (&0 or 1 as
above).
F_GETFL Get fildes status flags.
F_SETFL Set fildes status flags to the integer value
given as the third argument. Only certain
flags can be set [see fcntl(5)].
F_FREESP Free storage space associated with a section
of the ordinary file fildes. The section is
specified by a variable of data type struct
flock pointed to by the third argument arg.
The data type struct flock is defined in the
<fcntl.h> header file [see fcntl(5)] and con-
tains the following members: l_whence is 0,
1, or 2 to indicate that the relative offset
l_start will be measured from the start of the
file, the current position, or the end of the
file, respectively. l_start is the offset
from the position specified in l_whence.
l_len is the size of the section. An l_len of
0 frees up to the end of the file; in this
case, the end of file (i.e., file size) is set
to the beginning of the section freed. Any
data previously written into this section is
no longer accessible.
The following commands are used for record-locking. Locks
may be placed on an entire file or on segments of a file.
F_SETLK Set or clear a file segment lock according to
the flock structure that arg points to [see
fcntl(5)]. The cmd BF_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, fcntl will block until the segment is
free to be locked.
F_GETLK If the lock request described by the flock
structure that arg points to could be created,
then the structure is passed back unchanged
except that the lock type is set to F_UNLCK
and the l_whence field will be set to
Page 2 Printed 11/19/92
FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
SEEK_SET.
If a lock is found that would prevent this
lock from being created, then the structure is
overwritten with a description of the first
lock that is preventing such a lock from being
created. The structure also contains the pro-
cess ID and the system ID of the process hold-
ing the lock.
This command never creates a lock; it tests
whether a particular lock could be created.
F_RSETLK Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
F_RSETLKW Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
F_RGETLK Used by the network lock daemon, lockd(3N), to
communicate with the NFS server kernel to han-
dle locks on NFS files.
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 and no read
locks 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 flock structure 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. 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 0. If
such a lock also has l_whence and l_start set to 0, the
whole file will be locked. Changing or unlocking a segment
from the middle of a larger locked segment leaves two
smaller segments at 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.
Printed 11/19/92 Page 3
FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
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)], creat(2), open(2), read(2) and write(2) sys-
tem calls issued on the file will be affected by the record
locks in effect.
fcntl will fail if one or more of the following are true:
EACCES cmd is F_SETLK, the type of lock (l_type) is a
read lock (F_RDLCK) and the segment of a file
to be locked is already write locked by
another process, or the type is a write lock
(F_WRLCK) and the segment of a file to be
locked is already read or write locked by
another process.
EAGAIN cmd is F_FREESP, the file exists, mandatory
file/record locking is set, and there are out-
standing record locks on the file.
EAGAIN cmd is F_SETLK or F_SETLKW and the file is
currently being mapped to virtual memory via
mmap [see mmap(2)].
EBADF fildes is not a valid open file descriptor.
EBADF cmd is F_SETLK or F_SETLKW, the type of lock
(l_type) is a read lock (F_RDLCK), and fildes
is not a valid file descriptor open for read-
ing.
EBADF cmd is F_SETLK or F_SETLKW, the type of lock
(l_type) is a write lock (F_WRLCK), and fildes
is not a valid file descriptor open for writ-
ing.
EBADF cmd is F_FREESP, and fildes is not a valid
file descriptor open for writing.
EDEADLK cmd is F_SETLKW, the lock is blocked by some
lock from another process, and if fcntl
blocked the calling process waiting for that
lock to become free, a deadlock would occur.
EDEADLK cmd is F_FREESP, mandatory record locking is
enabled, O_NDELAY and O_NONBLOCK are clear and
a deadlock condition was detected.
Page 4 Printed 11/19/92
FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
EFAULT cmd is F_FREESP and the value pointed to by
the third argument arg resulted in an address
outside the process's allocated address space.
EFAULT cmd is F_GETLK, F_SETLK or F_SETLKW and the
value pointed to by the third argument
resulted in an address outside the program
address space.
EINTR A signal was caught during execution of the
fcntl system call.
EIO An I/O error occurred while reading from or
writing to the file system.
EMFILE cmd is F_DUPFD and the number of file descrip-
tors currently open in the calling process is
the configured value for the maximum number of
open file descriptors allowed each user.
EINVAL cmd is F_DUPFD and the third argument is
either negative, or greater than or equal to
the configured value for the maximum number of
open file descriptors allowed each user.
EINVAL cmd is not a valid value.
EINVAL cmd is F_GETLK, F_SETLK, or F_SETLKW and the
third argument or the data it points to is not
valid, or fildes refers to a file that does
not support locking.
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.
ENOLINK fildes is on a remote machine and the link to
that machine is no longer active.
ENOLINK cmd is F_FREESP, the file is on a remote
machine, and the link to that machine is no
longer active.
EOVERFLOW cmd is F_GETLK and the process ID of the pro-
cess holding the requested lock is too large
to be stored in the l_pid field.
SEE ALSO
close(2), creat(2), dup(2), exec(2), fork(2), open(2),
pipe(2), fcntl(5).
Printed 11/19/92 Page 5
FCNTL(2-SVR4) RISC/os Reference Manual FCNTL(2-SVR4)
The "File and Record Locking" chapter in the Application
Programmer's Guide.
DIAGNOSTICS
On success, fcntl returns a value that depends on cmd:
F_DUPFD A new file descriptor.
F_GETFD Value of flag (only the low-order bit is
defined). The return value will not be nega-
tive.
F_SETFD Value other than -1.
F_FREESP Value of 0.
F_GETFL Value of file status flags. The return value
will not be negative.
F_SETFL Value other than -1.
F_GETLK Value other than -1.
F_SETLK Value other than -1.
F_SETLKW Value other than -1.
On failure, fcntl returns -1 and sets errno to indicate the
error.
NOTES
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. Therefore, portable application
programs should expect and test for either value.
Page 6 Printed 11/19/92