fcntl(2) CLIX fcntl(2)
NAME
fcntl - Controls open file descriptors
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <sys/types.h>
#include <unistd.h>
#include <fcntl.h>
int fcntl(
int filedes ,
int command ,
int argument );
PARAMETERS
filedes Specifies an open file descriptor obtained from a successful
open(), creat(), fcntl(), pipe(), accept(), socket(), or
socketpair() function.
command Specifies the operation to be performed.
argument Specifies a variable that depends on the value of the command
parameter.
DESCRIPTION
The fcntl() function performs controlling operations on the open file
specified by the filedes parameter.
The following commands parameter values get a file descriptor or
associated flags or set those flags:
F_DUPFD Returns a new file descriptor as follows:
⊕ Lowest numbered available file descriptor greater than or
equal to the argument parameter.
⊕ Same open file (or pipe) as the original file.
⊕ Same file pointer as the original file (that is, both file
descriptors share one file pointer if the object is a file).
⊕ Same access mode (read, write, or read-write).
2/94 - Intergraph Corporation 1
fcntl(2) CLIX fcntl(2)
⊕ Same file status flags. (That is, both file descriptors
share the same file status flags.)
⊕ The close-on-exec flag (FD_CLOEXEC bit) associated with the
new file descriptor is set to remain open across exec()
functions.
F_GETFD Gets the close-on-exec flag (FD_CLOEXEC bit) associated with
the file descriptor filedes. The argument parameter is
ignored. If the low-order bit is 0, the file will remain open
across exec() function calls. Otherwise, the file will be
closed when an exec() function is executed.
F_SETFD Sets the close-on-exec flag (FD_CLOEXEC bit) associated with
the filedes parameter to the value of the argument parameter (0
or 1 as above).
F_GETFL Gets the file status flags for the file referred to by the
filedes parameter. The argument parameter is ignored.
F_SETFL Sets the file status flags to the argument parameter for the
file to which the filedes parameter refers. Only certain flags
can be set.
F_GETLK Gets the first lock that blocks the lock description given by
the variable of type struct flock pointed to by argument. 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, the structure is passed
back unchanged (except for the lock type, which will be set to
F_UNLCK).
F_SETLK Sets or clears a file segment lock according to the variable of
type struct flock pointed to by argument. The F_SETLK command
is used to establish read (F_RDLCK) and write (F_WRLCK) locks
and remove either type of lock (F_UNLCK) (see fcntl.h). If a
read or write lock cannot be set, fcntl() returns immediately
with 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 sleeps until
the segment is free to be locked.
F_GETOWN Gets the process ID or process group currently receiving SIGIO
and SIGURG signals. Process groups are returned as negative
values.
F_SETOWN Sets the process or process group to receive SIGIO and SIGURG
signals. Process groups are specified by supplying the
argument parameter as negative; otherwise, the argument
parameter is interpreted as a process ID.
2 Intergraph Corporation - 2/94
fcntl(2) CLIX fcntl(2)
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 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 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 RFS system ID (l_sysid) of the file segment to be affected. The
process ID and system ID fields are used only with the F_GETLK command to
return the values for a blocking lock. Locks may start and extend beyond
the current end of a 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 is 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 removes the old lock type and the new lock type takes
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 when
the process holding that file descriptor terminates. Locks are not
inherited by a child process in a fork() function.
When mandatory file and record locking is active on a file (see the
chmod() function), read() and write() functions issued on the file will be
affected by the record locks in effect.
EXAMPLES
1. To get a file current status flags:
flags = fcntl(fildes, F_GETFL, 0);
if(flags == -1)
perror("fcntl F_GETFL failed");
2. To set a file segment write lock for an entire file, waiting for any
existing lock holders to release the lock:
struct flock fl;
fl.l_type = F_WRLCK;
fl.l_whence = 0;
fl.l_start = 0;
fl.l_len = 0;
if (fcntl(fildes, F_SETLKW, &fl) == -1)
perror("fcntl F_SETLKW failed");
2/94 - Intergraph Corporation 3
fcntl(2) CLIX fcntl(2)
RETURN VALUES
Upon successful completion, the value returned depends on the value of the
command parameter as follows:
command Return Value
______________________________________________________________________
F_DUPFD A new file descriptor.
F_GETFD The value of the flag (only the FD_CLOEXEC bit is defined).
F_SETFD A value other than -1.
F_GETFL The value of file flags.
F_SETFL A value other than -1.
F_GETLK A value other than -1.
F_SETLK A value other than -1.
F_SETLKW A value other than -1.
F_GETOWN The value of the descriptor owner.
F_SETOWN A value other than -1.
If fcntl fails, a value of -1 is returned and the global variable errno is
set to indicate the error.
ERRORS
The fcntl() function fails if one or more of the following are true:
[EBADF] The filedes parameter is not a valid open file descriptor, or
the command parameter is F_GETOWN or F_SETOWN and the
descriptor does not reference a socket.
[EMFILE] The command parameter is F_DUPFD and OPEN_MAX file descriptors
are currently open.
[EINVAL] The command parameter is F_DUPFD and the argument parameter is
either negative or greater than or equal to OPEN_MAX.
[EINVAL] The command parameter is F_GETLK, F_SETLK, F_SETLKW, and
argument or the data it points to is not valid.
[ESRCH] The value of the command parameter is F_SETOWN and the process
ID given as argument is not in use.
[EACCES] The command parameter is F_SETLK, the type of lock (l_type) is
a read (F_RDLCK) lock, and the file segment to be locked is
write-locked by another process. This error also occurs if
the type is a write (F_WRLCK) lock and the segment of a file
to be locked is read- or write-locked by another process.
[ENOLCK] The command parameter is F_SETLK or F_SETLKW, the type of lock
is a read or write lock, and no more record locks are
available because the system maximum has been exceeded.
4 Intergraph Corporation - 2/94
fcntl(2) CLIX fcntl(2)
[EDEADLK] The command parameter is F_SETLKW and the lock is blocked by
some lock from another process. Putting the calling process
to sleep, waiting for that lock to become free, would cause a
deadlock.
[EFAULT] The command parameter is F_SETLK and argument points outside
the program address space.
[EINTR] A signal was caught during the fcntl() function.
[ENOLINK] The fildes parameter is on a remote machine and the link to
that machine is no longer active.
RELATED INFORMATION
Functions: accept(2), close(2), creat(2), dup2(2), exec(2), pipe(2),
open(2), socket(2), socketpair(2)
Files: fcntl(0)
2/94 - Intergraph Corporation 5