fcntl, dup, dup2 - Control open file descriptors
#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 );
Interfaces documented on this reference page conform to
industry standards 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.
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 parameter. The standard
allows for a list of variables, but does not specify
them. These can vary with each vendor's implementation of
this function. Specifies an open file descriptor that is
returned by the dup2() function. Specifies an open file
descriptor that is returned by the dup2() function.
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 descriptors 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
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. [Tru64 UNIX] Retrieves the current times
for the file identified by filedes. For the F_GETTIMES and
F_SETTIMES 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 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. 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 daemon (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 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: 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 [Toc] [Back]
[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 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.
[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, however, 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 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.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.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.
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).
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.
The fcntl() function sets errno to the specified values
for the following 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 descriptors 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 kernel
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 descriptor 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 interrupted 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.
Functions: close(2), creat(2), dup(2), exec(2), flock(2),
fork(2), getdtablesize(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)
[ Back ] |