 |
Index for Section 2 |
|
 |
Alphabetical listing for F |
|
fcntl(2)
NAME
fcntl, dup, dup2 - Control open file descriptors
SYNOPSIS
#include <fcntl.h>
#include <sys/types.h>
#include <unistd.h>
int fcntl (
int filedes,
int request [ ,
int argument | struct flock *argument |
advfs_opT *argument ] );
int dup(
int filedes );
int dup2(
int old,
int new );
STANDARDS
Interfaces documented on this reference page conform to industry standards
as follows:
dup(), dup2(): XPG4
fcntl(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
filedes Specifies an open file descriptor obtained from a successful
open(), fcntl(), or pipe() function.
request Specifies the operation to be performed.
argument Specifies a variable that depends on the value of the request
parameter.
old Specifies an open file descriptor that is returned by the dup2()
function.
new Specifies an open file descriptor that is returned by the dup2()
function.
DESCRIPTION
The fcntl() function performs controlling operations on the open file
specified by the filedes parameter.
When the fcntl(), dup() and dup2() functions need to block, only the
calling thread is suspended rather than all threads in the calling process.
The following are values for the request parameter:
F_DUPFD Returns a new file descriptor as follows:
·
Lowest numbered available file descriptor greater than or equal
to the argument parameter, taken as type int.
·
Same object references 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).
·
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 cleared so that the file will remain open
across exec functions.
F_GETFD Gets the value of the close-on-exec flag associated with the file
descriptor filedes. File descriptor flags are associated with a
single file descriptor and do not affect other file descriptors
that refer to the same file. The argument parameter is ignored.
F_SETFD Sets the close-on-exec flag associated with the filedes parameter
to the value of the argument parameter, taken as type int. If
the argument parameter is 0 (zero), the file remains open across
the exec functions. If the argument parameter is FD_CLOEXEC, the
file is closed on successful execution of the next exec function.
F_GETFL Gets the file status flags and file access modes for the file
referred to by the filedes parameter. The file access modes can
be extracted by using the mask O_ACCMODE on the return value.
File status flags and file access modes are associated with the
file description and do not affect other file descriptors that
refer to the same file with different open file descriptions.
The argument parameter is ignored.
F_SETFL Sets the file status flags to the argument parameter, taken as
type int, for the file to which the filedes parameter refers.
The file access mode is not changed.
F_GETOWN [XPG4-UNIX] If filedes refers to a socket, gets the process or
process group ID currently receiving SIGURG signals when out-of-
band data is available. Positive values indicate a process ID;
negative values, other than -1, indicate a process group ID.
F_SETOWN [XPG4-UNIX] If filedes refers to a socket, sets the process or
process group ID to receive SIGURG signals when out-of-band data
is available, using the value of the argument parameter, taken as
type int. Positive values indicate a process ID; negative values,
other than -1, indicate a process group ID.
F_RSETLK [DIGITAL] Is used by the network lock daemon (rpc.lockd(8)) to
communicate with the NFS server kernel to handle locks on the NFS
files.
F_RSETLKW [DIGITAL] Is used by the network lock daemon (rpc.lockd(8)) to
communicate with the NFS server kernel to handle locks on the NFS
files.
F_RGETLK [DIGITAL] Is used by the network lock daemon (rpc.lockd(8)) to
communicate with the NFS server kernel to handle locks on the NFS
files.
F_CNVT [DIGITAL] Is used by the network lock daemon (rpc.lockd(8)) to
communicate with the NFS server kernel to handle locks on the NFS
files.
F_ADVFS_OP
[DIGITAL] Performs AdvFS-specific operations on AdvFS files.
The value expects that the argument parameter is a pointer to a
advfs_opT structure as described in the <fcntl.h> header file.
The following values for the request parameter are available for record
locking:
F_GETLK Gets the first lock that blocks the lock description pointed to
by the argument parameter, taken as a pointer to type struct
flock. The information retrieved overwrites the information
passed to the fcntl() function in the flock structure. If no
lock is found that would prevent this lock from being created,
then the structure is left unchanged except for the lock type,
which is set to F_UNLCK.
F_SETLK Sets or clears a file segment lock according to the lock
description pointed to by argument, taken as a pointer to type
struct flock. F_SETLK is used to establish shared locks
(F_RDLCK), or exclusive locks (F_WRLCK), as well as remove either
type of lock (F_UNLCK). If a shared (read) or exclusive (write)
lock cannot be set, the fcntl() function returns immediately with
a value of -1.
F_SETLKW Same as F_SETLK except that if a shared or exclusive lock is
blocked by other locks, the process will wait until it is
unblocked. If a signal is received while fcntl() is waiting for
a region, the function is interrupted, -1 is returned, and errno
is set to [EINTR].
[DIGITAL] The O_NDELAY and O_NONBLOCK requests affect only operations
against file descriptors derived from the same open() function. In BSD,
these apply to all file descriptors that refer to the object.
When a shared lock is set on a segment of a file, other processes are able
to set shared locks on that segment or a portion of it. A shared lock
prevents any other process from setting an exclusive lock on any portion of
the protected area. A request for a shared lock fails if the file
descriptor was not opened with read access.
An exclusive lock prevents any other process from setting a shared lock or
an exclusive lock on any portion of the protected area. A request for an
exclusive lock fails if the file descriptor was not opened with write
access.
The flock structure describes the type (l_type), starting offset
(l_whence), relative offset (l_start), size (l_len) and process ID (l_pid)
of the segment of the file to be affected.
The value of l_whence is set to SEEK_SET, SEEK_CUR or SEEK_END, to indicate
that the relative offset l_start bytes is measured from the start of the
file, from the current position, or from the end of the file, respectively.
The value of l_len is the number of consecutive bytes to be locked. The
l_len value may be negative (where the definition of off_t permits negative
values of l_len). 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 becomes SEEK_SET.
If l_len is positive, the area affected starts at l_start and ends at
l_start + l_len - 1. If l_len is negative, the area affected starts at
l_start + l_len and ends at l_start - 1. Locks may start and extend beyond
the current end of a file, but may not be negative relative to the
beginning of the file. If l_len is set to 0 (zero), a lock may be set to
always extend to the largest possible value of the file offset for that
file. If such a lock also has l_start set to 0 (zero) and l_whence is set
to SEEK_SET, the whole file is locked.
Changing or unlocking a portion from the middle of a larger locked segment
leaves a smaller segment 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.
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() function.
[DIGITAL] The fcntl() record locks are implemented in the kernel for local
locks and throughout the network by the network lock daemon (rpc.lockd(8))
for remote locks on NFS files. If the file server crashes and has to be
rebooted, the lock daemon attempts to recover all locks that were
associated with that server. If a lock cannot be reclaimed, the process
that held the lock is issued a SIGLOST signal.
[DIGITAL] In order to maintain consistency in the network case, data must
not be cached on client machines. For this reason, file buffering for an
NFS file is turned off when the first lock is attempted on the file.
Buffering remains off as long as the file is open. Programs that do I/O
buffering in the user address space, however, may have inconsistent
results. The standard I/O package, for instance, is a common source of
unexpected buffering.
[DIGITAL] If a regular file has enforced record locking enabled, record
locks on the file will affect calls to other calls, including creat(),
open(), read(), write(), truncate(), and ftruncate().
A potential for deadlock occurs if a process controlling a locked region is
put to sleep by attempting to lock another process' locked region. If the
system detects that sleeping until a locked region is unlocked would cause
a deadlock, the fcntl() function fails with an [EDEADLK] error.
[DIGITAL] The F_ADVFS_OP request is used to perform operations on AdvFS
files which do not have an analog on other file systems. The argument
parameter is expected to be a pointer to an advfs_opT structure. The
version field of the advfs_opT structure must be specified and set to
ADVFS_OP_CURR_VERSION. It provides an in-memory check for the version of
the structure. The operation field of the advfs_opT structure specifies
the general kind of operation. The action field of the advfs_opT structure
refines the operation field in order to specify more exactly the operation
to be performed. If the action specified is ADVFS_GET_INFO, the info_buf
and info_buf_size fields also must be used. The info_buf field is a
pointer to the buffer that will contain the requested information. The
info_buf_size field specifies the size of the buffer. See the <fcntl.h>
header file for a description of the operations, actions, and values
returned by ADVFS_GET_INFO.
To use the F_ADVFS_OP request on AdvFS files that are mounted across NFS,
the NFS property list daemon, proplistd, must be running on the NFS client
and the fileset must have been mounted on the client using the proplist
option.
The following code fragment shows how to activate atomic write data logging
on an AdvFS file:
.
.
.
advfs_opT myop;
int fd;
.
.
.
myop.version = ADVFS_OP_CURR_VERSION;
myop.operation = ADVFS_AW_DATA_LOGGING;
myop.action = ADVFS_ACTIVATE;
ret = fcntl(fd, F_ADVFS_OP, &myop);
.
.
.
The following code fragment shows how to query the current I/O mode for an
AdvFS file:
.
.
.
advfs_opT myop;
int fd;
int io_mode;
.
.
.
myop.version = ADVFS_OP_CURR_VERSION;
myop.operation = advfs_aw_data_logging;
myop.action = ADVFS_GET_INFO;
myop.info_buf = &io_mode;
myop.info_buf_size = sizeof(int):
ret = fcntl(fd, F_ADVFS_OP, &myop):
if (ret) {
perror("fcntl failed");
}
if (io_mode == ADVFS_ASYNC_IO)
printf("I/O mode is asynchronous.\n");
else if (io_mode == ADVFS_DATA_LOGGING_IO)
printf("I/O mode is atomic write data logging.\n");
else if (io_mode == ADVFS_SYNC_IO)
printf("I/O mode is forced synchronous writes.\n");
.
.
.
See chfile(8) for information on the file's I/O mode. Note that the
previous example is attempting to determine the I/O mode setting. The
setting could also have been specified as ADVFS_SYNC_WRITE.
NOTES
The dup(filedes) function is equivalent to fcntl(filedes, F_DUPFD, 0).
The dup2(oldfiledes, newfiledes) function has similar functionality to:
close(newfiledes)
fcntl(oldfiledes, F_DUPFD, newfiledes)
The file locks set by the fcntl() and lockf() functions do not interact in
any way with the file locks set by the flock()function. If a process sets
an exclusive lock on a file using the fcntl() or lockf() function, the lock
will not affect any process that is setting or clearing locks on the same
file using the flock() function. It is therefore possible for an
inconsistency to arise if a file is locked by different processes using
flock() and fcntl(). (The fcntl() and lockf() functions use the same
mechanism for record locking.)
RETURN VALUES
Upon successful completion, the value returned depends on the value of the
request parameter as follows:
F_DUPFD Returns a new file descriptor.
F_GETFD Returns FD_CLOEXEC or 0 (zero).
F_SETFD Returns a value other than -1.
F_GETFL Returns the value of file status flags and access modes. (The
return value will not be negative.)
F_SETFL Returns a value other than -1.
F_GETLK Returns a value other than -1.
F_SETLK Returns a value other than -1.
F_GETOWN [XPG4-UNIX] Returns the value of the socket owner process or
process group; this will not be -1.
F_SETOWN [XPG4-UNIX] Returns a value other than -1.
F_SETLKW Returns a value other than -1.
If the fcntl() function fails, a value of -1 is returned and errno is set
to indicate the error.
ERRORS
The fcntl() function sets errno to the specified values for the following
conditions:
[EACCES] or [EAGAIN]
The request parameter is F_SETLK; the type of lock (l_type) is a
shared (F_RDLCK) or exclusive (F_WRLCK) lock, and the segment of
a file to be locked is already exclusive-locked by another
process, or the type is an exclusive lock and some portion of the
segment of a file to be locked is already shared-locked or
exclusive-locked by another process.
[EBADF] The filedes or old parameter is not a valid open file descriptor
and the argument parameter file descriptor is negative or greater
than or equal to the per-process limit.
The request parameter is F_SETLK or F_SETLKW, the type of lock
(l_type) is a shared lock (F_RDLCK), and filedes is not a valid
file descriptor open for reading.
The type of lock (l_type) is an exclusive lock (F_WRLCK), and
filedes is not a valid file descriptor open for writing.
[EDEADLK] The request parameter is F_SETLKW, the lock is blocked by some
lock from another process and putting the calling process to
sleep, and waiting for that lock to become free would cause a
deadlock.
[EFAULT] The argument parameter is an invalid address.
[EINVAL] The request parameter is F_DUPFD and the argument parameter is
negative or greater than or equal to OPEN_MAX.
[DIGITAL] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked.
An illegal value was provided for the request parameter.
The request parameter is F_GETLK, F_SETLK, or F_SETLKW and the
data pointed to by argument is invalid, or filedes refers to a
file that does not support locking.
[DIGITAL] The F_ADVFS_OP request was performed and the fd
referred to a socket; or the action was ADVFS_GET_INFO and the
info_buf_size was zero; or the operation to be performed was
undefined; or the action to be taken was undefined.
[EMFILE] The request parameter is F_DUPFD and too many or OPEN_MAX file
descriptors are currently open in the calling process, or no file
descriptors greater than or equal to argument are available.
[DIGITAL] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked.
[ESRCH] [DIGITAL] The value of the request parameter is F_SETOWN and the
process ID given as argument is not in use.
[EINTR] The request parameter is F_SETLKW and the fcntl() function was
interrupted by a signal which was caught.
[ENOLCK] The request parameter is F_SETLK or F_SETLKW and satisfying the
lock or unlock request would exceed the configurable system limit
of NLOCK_RECORD.
[DIGITAL] The file is an NFS file, and either the client or
server system is not running rpc.lockd, which is the NFS lock
manager.
[ENOMEM] [DIGITAL] The system was unable to allocate kernel memory for
the requested file descriptor.
[ENOTTY] [DIGITAL] The request parameter is F_SETOWN and the calling
process does not have a controlling terminal, the file is not the
controlling terminal, or the controlling terminal is no longer
associated with the calling process' session.
[EPERM] [DIGITAL] The request parameter is F_SETOWN and the argument
specified by the pgrp_id is valid, but matches a process ID or
process group ID of a process in another session.
The dup() and dup2() functions set errno to the specified values for the
following conditions:
[EACCES] The request parameter 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.
[EBADF] The filedes or old parameter is not a valid open file descriptor
or the new parameter file descriptor is negative or greater than
OPEN_MAX.
[DIGITAL] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked.
[EINTR] The dup2() function was interrupted by a signal which was caught.
[EMFILE] The number of file descriptors exceeds OPEN_MAX or the per-
process limit, or there is no file descriptor above the value of
the new parameter.
[ENETUNREACH]
[DIGITAL] The file descriptor specified by filedes is on a remote
machine and the link to that machine is no longer active.
[ENOMEM] [DIGITAL] The system was unable to allocate kernel memory for the
requested file descriptor.
Because in the future the variable errno is set to EAGAIN rather than
EACCES when a section of a file is already locked by another process,
portable application programs should expect and test for either value.
RELATED INFORMATION
Functions: close(2), exec(2), lockf(3), open(2), read(2), truncate(2),
write(2) creat(2), dup(2), fork(2), pipe(2), getdtablesize(2)
Commands: rpc.lockd(8), rpc.statd(8)
Standards: standards(5)