fcntl(2)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 stan‐
dards as follows:
dup(), dup2(): XSH4.0, XSH4.2, XSH5.0
fcntl(): XSH4.0, XSH4.2,XSH5.0, XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Specifies an open file descriptor obtained from a successful open(),
fcntl(), or pipe() function. Specifies the operation to be performed.
Specifies a variable that depends on the value of the request parame‐
ter. The standard allows for a list of variables, but does not specify
them. These can vary with each vendor's implementation of this func‐
tion. Specifies an open file descriptor that is returned by the dup2()
function. 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:
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 options. (That is, both file descrip‐
tors share the same file status options). The close-on-exec option
(FD_CLOEXEC bit) associated with the new file descriptor is cleared so
that the file will remain open across exec functions. Gets the value
of the close-on-exec option associated with the file descriptor
filedes. File descriptor options 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. Sets the close-on-exec
option associated with the filedes parameter to the value of the argu‐
ment parameter, taken as type int. If the argument parameter is 0
(zero), the file remains open across the exec functions. If the argu‐
ment parameter is FD_CLOEXEC, the file is closed on successful execu‐
tion of the next exec function. [Tru64 UNIX] Retrieves the current
times for the file identified by filedes. For the F_GETTIMES and F_SET‐
TIMES requests, the function's third argument is a pointer to the
struct attr_timbuf structure (defined in sys/fcntl1.h), which contains
the file's atime (access time), mtime (modification time), and ctime
(file attribute change time) values. These requests are useful for
operations, such as backup and archiving, when it is necessary to save
a file's current time values and then, after copying or moving the
file, set back atime or mtime without changing ctime. [Tru64
UNIX] Sets the current times for the file identified by filedes. This
request requires superuser privilege and returns the [EPERM] error on
an attempt to set the file's times without this privilege.
The following example illustrates how to use the F_GETTIMES and
F_SETTIMES requests:
# include <stdio.h> # include <sys/fcntl.h> # include
<sys/fcntl1.h> main() {
char buffer[1024];
int fd,bytesread;
struct attr_timbuf tstamp;
/* Create a file*/
fd=open("/usr/tmp/foo",O_CREAT|O_RDONLY);
if(fd > 0) {
/* Display the atime and ctime of the file */
printf("atime before reading the file:\n");
system("ls -lu /usr/tmp/foo");
printf("ctime before reading the file:\n");
system("ls -lc /usr/tmp/foo");
if(fcntl(fd,F_GETTIMES,&tstamp) < 0) {
perror("fcntl:F_GETTIMES");
exit(1);
}
}
else {
perror("open");
exit(1);
}
printf("Sleeping for one minute because ls commands can \
show time change only in terms of hours and minutes...\n");
sleep(60);
/* Access the file */
bytesread=read(fd,buffer,1024);
if(bytesread >= 0) {
/* Again display the atime and ctime of the file */
printf("\n\natime after reading the file:\n");
system( "ls -lu /usr/tmp/foo");
printf("ctime after reading the file:\n");
system( "ls -lc /usr/tmp/foo");
/* Now use F_SETTIMES to reinstate the original atime */
if(fcntl(fd,F_SETTIMES,&tstamp) < 0) {
perror("fcntl:F_SETTIMES");
exit(1);
}
else {
printf("\n\nAfter using F_SETTIMES, atime is
reset \ without affecting ctime\n");
printf("\tatime:\n");
system( "ls -lu /usr/tmp/foo");
printf("\tctime:\n");
system( "ls -lc /usr/tmp/foo");
}
}
else
perror("read");
system("rm -rf /usr/tmp/foo"); } Gets the file status
options 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
options 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. Sets the file status options to
the argument parameter, taken as type int, for the file to which
the filedes parameter refers. The file access mode is not
changed.
[XNS5.0] 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. If filedes does not refer
to a socket, the results are unknown. [XNS5.0] If filedes refers to
a socket, sets the process or process group ID to receive SIGURG sig‐
nals when out-of-band data is available, using the value of the argu‐
ment parameter, taken as type int. Positive values indicate a process
ID; negative values, other than -1, indicate a process group ID. If
filedes does not refer to a socket, the results are unknown. [Tru64
UNIX] Reserved for use by the network lock daemon (rpc.lockd(8)) on
NFS servers to acquire locks requested by F_SETLK on NFS clients.
[Tru64 UNIX] Reserved for use by the network lock daemon
(rpc.lockd(8)) on NFS servers to acquire locks requested by F_SETLK on
NFS clients. [Tru64 UNIX] Reserved for use by the network lock dae‐
mon (rpc.lockd(8)) on NFS servers to acquire locks requested by F_SETLK
on NFS clients. [Tru64 UNIX] Is used by the network lock daemon
(rpc.lockd(8)) to communicate with the NFS server kernel to handle
locks on the NFS files. [Tru64 UNIX] Performs AdvFS-specific opera‐
tions 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: 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. 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.
An unlock (F_UNLCK) request in which l_len is nonzero and the
offset of the last byte of the requested segment is the maximum
value for an object of type off_t, when the process has an
existing lock in which l_len is 0 and which includes the last
byte of the requested segment, is treated as a request to unlock
from the start of the requested segment with an l_len equal to
0. Otherwise, an unlock (F_UNLCK) request attempts to unlock
only the requested file. 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].
AdvFS-only request Parameters
[Tru64 UNIX] The following values for the request parameter are
available for AdvFS only, and relate to performing direct I/O. The
arguments used with these request parameters are in the <fcntl.h> file.
FCACHE is defined as zero to indicate that the file's cache policy is
the file system's default cache policy. FDIRECTIO is defined as one to
indicate that the file's cache policy is direct I/O. Gets the cache
policy for the file, which is either direct I/O or caching.
[Tru64 UNIX] The following value for the request parameter is valid
only when the filedes parameter describes an AdvFS or UFS file.
[Tru64 UNIX] The F_GETMAP request gets the sparseness map of the file
referred to by the fildes parameter. The argument parameter, taken as a
pointer to type struct extentmap, is filled in with data that describes
the extent map of the file.
Each map entry is declared as:
struct extentmapentry {
unsigned long offset;
unsigned long size; }; struct extentmap {
unsigned long arraysize;
unsigned long numextents;
unsigned long offset;
struct extentmapentry *extent; };
The map returned by this function can be different from the
actual number of extents (or their definition) when the file is
being written. It is recommended that you use this function only
on files that are not being written.
[Tru64 UNIX] The O_NDELAY and O_NONBLOCK requests affect only opera‐
tions 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 defini‐
tion 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 seg‐
ment 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.
[Tru64 UNIX] 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.
[Tru64 UNIX] 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, how‐
ever, may have inconsistent results. The standard I/O package, for
instance, is a common source of unexpected buffering.
[Tru64 UNIX] 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.
[Tru64 UNIX] 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 struc‐
ture. The operation field of the advfs_opT structure specifies the gen‐
eral kind of operation. The action field of the advfs_opT structure
refines the operation field in order to specify more exactly the opera‐
tion 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.operation = ADVFS_AW_DATA_LOGGING; myop.action = ADVFS_ACTI‐
VATE; 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.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) and fcntl(oldfiledes, F_DUPFD, newfiledes).
RETURN VALUES
Upon successful completion, the value returned depends on the value of
the request parameter as follows: Returns a new file descriptor.
Returns FD_CLOEXEC or 0 (zero). Returns a value other than -1.
Returns the value of file status options and access modes. (The return
value will not be negative.) Returns a value other than -1. Returns a
value other than -1. Returns a value other than -1. [XNS5.0]
Returns the value of the socket owner process or process group; this
will not be -1. [XNS5.0] Returns a value other than -1. Returns a
value other than -1. [Tru64 UNIX] Returns a value other than -1.
[Tru64 UNIX] Returns a value other than -1. [Tru64 UNIX] Returns a
value other than -1. [Tru64 UNIX] 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 follow‐
ing conditions:
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.
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. 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.
[Tru64 UNIX] The request parameter is F_GETMAP and the filedes
parameter does not point to an open file descriptor of an AdvFS
or UFS file.
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. 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.
The argument parameter is an invalid address. The request
parameter is F_DUPFD and the argument parameter is negative or
greater than or equal to OPEN_MAX.
[Tru64 UNIX] 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.
[Tru64 UNIX] 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. The request
parameter is F_DUPFD and too many or OPEN_MAX file descriptors
are currently open in the calling process, or no file descrip‐
tors greater than or equal to argument are available.
[Tru64 UNIX] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked. One of the values to be returned
cannot be represented correctly.
The request argument is F_BETLK, F_SETLK, or F_SETLKW and the
smallest or, if l_len is nonzero, the largest offset of any byte
in the requested segment cannot be represented correctly in an
object of type off_t. [Tru64 UNIX] The value of the request
parameter is F_SETOWN and the process ID given as argument is
not in use. The request parameter is F_SETLKW and the fcntl()
function was interrupted by a signal which was caught. [Tru64
UNIX] The request parameter is F_GETMAP and an I/O error
occurred on the disk where the file is located. 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.
[Tru64 UNIX] The file is an NFS file, and either the client or
server system is not running rpc.lockd, which is the NFS lock
manager. [Tru64 UNIX] The system was unable to allocate ker‐
nel memory for the requested file descriptor. [Tru64 UNIX]
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. [Tru64 UNIX] 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.
[Tru64 UNIX] The request parameter is F_SETTIMES and the user
does not have superuser privilege.
The dup() and dup2() functions set errno to the specified values for
the following conditions: 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. The filedes or old parameter
is not a valid open file descriptor or the new parameter file descrip‐
tor is negative or greater than OPEN_MAX.
[Tru64 UNIX] Either the OPEN_MAX value or the per-process soft
descriptor limit is checked. The dup2() function was inter‐
rupted by a signal which was caught. 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.
[Tru64 UNIX] The file descriptor specified by filedes is on a
remote machine and the link to that machine is no longer active.
[Tru64 UNIX] 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.
SEE ALSO
Functions: close(2), creat(2), dup(2), exec(2), flock(2), fork(2), get‐
dtablesize(2), open(2), pipe(2), read(2), truncate(2), write(2),
lockf(3)
Commands: rpc.lockd(8), rpc.statd(8)
Standards: standards(5)
Network Programmer's Guide
fcntl(2)
