fcntl(2) DG/UX R4.11MU05 fcntl(2)
NAME
fcntl - file descriptor control
SYNOPSIS
#include <fcntl.h>
int fcntl (fildes, command, argument)
int fildes;
int command;
int argument;
where:
fildes A valid, active file descriptor
command A file control command
argument An argument, either an integer (when command is one of
F_DUPFD, F_DUP2, F_GETFD, F_SETFD, F_SETFL, F_GETOWN,
F_SETOWN or F_CHKFL) or a pointer to a struct flock (when
command is one of F_GETLK, F_SETLK, F_SETLKW or F_FREESP)
DESCRIPTION
The fcntl call provides a variety of operations on descriptors.
fildes is an active, valid descriptor. command is a file control
command to be performed on fildes using argument as an argument. Not
all commands require an argument. The commands available are:
F_DUPFD The first (lowest numbered) inactive descriptor of the
calling process, greater than or equal to argument, is made
a duplicate of fildes. Thus, both descriptors refer to the
same object pointer. The new descriptor's close-on-exec
attribute is set to remain open across exec operations.
This operation is equivalent to dup if argument is zero and
dup2 if argument is an inactive descriptor.
F_DUP2 Duplicate fildes onto a target descriptor, specified by
argument. If the target is already open, close it first.
This operation is equivalent to dup2.
F_SETFD Set the close-on-exec attribute of fildes to the low-order
bit of argument. If the low-order bit is 0, the file will
remain open across exec operations; otherwise, the file
will be closed upon execution of the exec operation.
F_GETFD Return the close-on-exec attribute of fildes.
F_SETOWN Invoke the type manager of the object to which fildes
refers to set the process id or process group id receiving
the SIGIO and SIGURG signals for the object. Process group
ids are specified by supplying argument as negative,
otherwise argument is interpreted as a process id.
F_GETOWN Query the type manager of the object to which fildes refers
for the process id or process group id currently receiving
SIGIO and SIGURG signals for the object. Process group ids
are returned as negative values.
F_SETFL Invoke the type manager of the object to which fildes
refers to set the object pointer status flag bits to
argument. Only the following flag bits may be set:
O_NONBLOCK, O_NDELAY, O_APPEND, O_SYNC, and FASYNC.
F_GETFL Query the type manager of the object to which fildes refers
for the object pointer status flag. The following flags
will be returned if set in the object pointer status flag:
O_NONBLOCK, O_NDELAY, O_APPEND, O_SYNC, FASYNC, O_RDWR,
O_RDONLY, and O_WRONLY.
F_SETLK Set or clear a file lock according to argument, which is
interpreted to be a pointer to a struct flock. F_SETLK is
used to set read locks, set write locks, or remove either
type of lock. If a read or a write lock cannot be set,
fcntl returns immediately with a value of -1.
F_SETLKW This command is the same as F_SETLK except if a read or
write lock is blocked by other locks, the process will pend
until the segment to be locked is free.
F_GETLK Get the first lock that blocks the lock description
specified by argument, which is interpreted to be a pointer
to a struct flock. The information retrieved overwrites
the information passed to fcntl in argument. If no lock is
found that would prevent this lock from being set, argument
is unchanged, except for the lock type, which is set to
F_UNLCK.
F_CHKFL Check argument to see if it would be valid if passed as the
argument to a F_SETFL fcntl command. Return 0 if valid, -1
if not.
F_FREESP Free storage space associated with the file descriptor
according to the struct flock pointed to by argument. The
portion to be freed is specified by lwhence, lstart and
llen. If the llen field is 0, the file is truncated.
Currently, the only supported operation is truncation (that
is, llen must be 0).
ACCESS CONTROL
None.
RETURN VALUE
The value returned may be one of the following regardless of the
value of command:
-1 An error occurred. errno is set to indicate the error.
If command is F_GETFD, the value returned may be one of the
following:
0 or 1 Completed successfully. The value of the close-on-exec
flag is returned.
If command is F_SETFD, F_SETFL, F_CHKFL, F_FREESP or F_SETOWN:
0 Completed successfully.
If command is F_DUPFD, the value returned may be one of the
following:
argument..NOFILE-1
Completed successfully. A new file descriptor is returned.
If command is F_DUP2, the value returned may be one of the following:
argument Completed successfully. The descriptor specified by
argument is returned.
If command is F_GETOWN, the value returned may be one of the
following:
owner Completed successfully. If the value is negative, -owner
is the process group id returned. Otherwise owner is a
process id. Note that the process group may be 1, in which
case, -1 will be returned.
If command is F_GETFL, the value returned may be one of the
following:
fileflags
Completed successfully. The value of the file flags is
returned.
If command is F_GETLK, F_SETLK, or F_SETLKW, the value returned may
be the following:
0 Completed successfully.
DIAGNOSTICS
Errno may be set to one of the following error codes regardless of
the value of command:
EBADF Fildes is not a valid, active descriptor.
EINVAL Command is not one of the known values; or argument is not
a valid descriptor; or the flock structure pointed to by
argument is outside the process's readable address space.
If command is F_DUPFD, errno may be set to one of these values:
EMFILE All descriptors are currently open.
If command is F_DUP2, errno may be set to one of these values:
EBADF One of the descriptors is out of range, or fildes refers to
an inactive descriptor.
If command is F_SETLK, F_SETLKW, or F_GETLK, errno may be set to one
of these values:
EBADF The caller requested a read or write lock, but does not
have read or write access to the channel.
EINTR The process was interrupted while attempting to get a lock
(F_GETLK), set or clear a lock (F_SETLK), or while pending
on a lock (F_SETLKW).
EDEADLK The command was F_SETLKW and a deadlock would exist if the
lock were granted.
EACCES The command was F_SETLK and the type of lock sought is a
read lock (F_RDLCK) or write lock (F_WRLCK), and the
segment of a file to be locked is already write-locked by
another process, or the type is a write lock and the
segment of a file to be locked is already read-locked or
write-locked by another process.
For a system with the DG/UX Cluster product: EACCES can
also indicate that the file is locked by another node in
the cluster, and the F_SETLKW or F_SETLK function was
specified. Also note that, on a system with the DG/UX
Cluster product, locks are promoted to the entire file.
For example, if a node has a shared lock on part of a file,
that shared lock appears to other nodes to cover the entire
file. If a node has an exclusive lock, that exclusive lock
appears to other nodes to cover the entire file.
Additional errors may be given by the type managers.
SEE ALSO
close(2), creat(2), dgflock(3C), dup(2), dup2(2), exec(2), fork(2),
getdtablesize(2), open(2), pipe(2), sigvec(2), socket(2),
socketpair(2), fcntl(5).
Licensed material--property of copyright holder(s)