![](/img/s.gif) |
» |
|
|
![Content starts here](/img/s.gif) |
NAMEfcntl() — file control SYNOPSIS#include <fcntl.h> int fcntl(int fildes, int cmd, ... /* arg */); RemarksThe ANSI C ", ...
" construct denotes a variable length argument list whose
optional [or required]
members are given in the associated comment
(/* */). DESCRIPTIONfcntl()
provides for control over open files.
fildes
is an open
file descriptor. The following are possible values for the
cmd
argument:
- F_ADVISE
Fadvise service request (see
fadvise(2)). - F_DUPFD
Return a new file descriptor having the following characteristics:
Lowest numbered available file descriptor greater than or equal to
the third argument,
arg,
taken as an integer of type
int. 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). 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 associated with the new file descriptor
is set to remain open across
exec()
system calls.
- F_GETFD
Get the file descriptor flags (defined in
<fcntl.h>)
that are associated with the file descriptor
fildes.
File descriptor flags are associated with a single file descriptor and do
not affect other file descriptors that refer to the same file. - F_SETFD
Set the file descriptor flags (defined in
<fcntl.h>)
that are associated with
fildes,
to the third argument,
arg,
taken as an integer of type
int
(see
F_GETFD).
If the
FD_CLOEXEC
flag in the third argument is
0,
the file will remain open across
exec();
otherwise, the file will be closed upon execution of
exec(). - F_GETFL
Get file status flags and access modes; see
fcntl(5). - F_SETFL
Set file status flags to
the third argument,
arg,
taken as an integer of type
int.
Only certain flags can be set; see
fcntl(5).
It is not possible to set both
O_NDELAY
and
O_NONBLOCK. - F_GETLK
Get the first lock that blocks the lock
described by the variable of type
struct flock
pointed to by the third argument,
arg,
taken as a pointer to type
struct flock.
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 that the lock type is set to
F_UNLCK. - F_SETLK
Set or clear a file segment lock according to the variable of type
struct flock
pointed to by
the third argument,
arg,
taken as a pointer to type
struct flock
(see
fcntl(5)).
The
cmd
F_SETLK
is used to establish read
(F_RDLCK)
and write
(F_WRLCK)
locks, as well as to remove either type of lock
(F_UNLCK).
If a read or write lock cannot be set,
fcntl()
returns immediately with an error value of
-1. - F_SETLKW
This
cmd
is the same as
F_SETLK
except that if a read or write lock is blocked by other locks,
the process will sleep until the segment is free to be locked. - F_GETLK64
Same as
F_GETLK,
except
arg
is a pointer to
struct flock64
instead of
struct flock. - F_SETLK64
Same as
F_SETLK,
except
arg
is a pointer to
struct flock64
instead of
struct flock. - F_SETLKW64
Same as
F_SETLKW,
except
arg
is a pointer to
struct flock64
instead of
struct flock. - F_GETOWN
If
fildes
refers to a socket,
fcntl()
returns the process or process group ID specified to receive
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
If
fildes
refers to a socket,
fcntl()
sets the process or process group
ID specified to receive
SIGURG
signals when out-of-band data is
available, using the value of the third argument, arg, taken
as type int. Positive values indicate a process ID; negative
values, other than -1, indicate a process group ID. - F_GETTIMES
Gets the current times for the file identified by
fildes.
The
F_GETTIMES
third argument,
arg,
is a pointer to the
struct attr_timbuf
defined in
<sys/fcntl1.h>
(see
F_SETTIMES). - F_SETTIMES
Sets the current times for the file identified by
fildes.
To execute the
cmd
without error,
F_SETTIMES
requires superuser privilege.
The
F_SETTIMES
third argument,
arg,
is a pointer to the
struct attr_timbuf
that is defined in
<sys/fcntl1.h>.
The
attr_timbuf
structure contains the file's
atime
(access time),
mtime
(modification time), and
ctime
(file attribute change time) values.
Here is the definition of the structure: struct attr_timbuf {
timestruc_t atime; /* access */
timestruc_t mtime; /* data modification */
timestruc_t ctime; /* attribute change */
}; This
cmd
is useful when it is necessary to save a file's current time values
and then, after copying or moving the file, set back
atime
and
mtime.
Note that
ctime
is not restored to the original value; the value of
ctime
after
F_SETTIMES
is file system dependent. An example using
F_GETTIMES
and
F_SETTIMES
follows: # include <sys/fcntl.h>
# include <sys/fcntl1.h>
int
main()
{
int fd ;
struct attr_timbuf tstamp;
/* Create a file*/
fd=open("/var/tmp/foo",O_CREAT|O_RDWR);
/* Use F_GETTIMES to obtain the current times
* of the file
*/
fcntl(fd,F_GETTIMES,&tstamp);
/* Access or modify fd */
/* Now use F_SETTIMES to reinstate the
* original atime and mtime.
*/
fcntl(fd,F_SETTIMES,&tstamp);
} - F_SHARE
Sets a share reservation on a file with the specified
access mode and designates which types of access to deny.
The details of the file share reservation request are specified
using the third argument
arg,
which should be a pointer to a
struct fshare
(defined in
<sys/fcntl.h>).
See the
File Share Reservations
section below. - F_UNSHARE
Removes an existing share reservation.
A read lock prevents any other process
from write-locking the protected area.
More than one read lock can exist
for a given segment of a file at a given time.
The file descriptor on which a read lock is being placed
must have been opened with read access. A write lock prevents any other 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 being placed
must have been opened with write access. The structure
flock
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 process ID field is only used with the
F_GETLK cmd
to return the value of a block in lock.
Locks can start and extend beyond the current end of a file,
but cannot be negative relative to the beginning of the file.
A lock can be set to always extend to the end of file by setting
l_len
to zero (0).
If such a lock also has
l_start
set to zero (0), the whole file will be locked.
Changing or unlocking a segment from the middle of a larger locked segment
leaves two smaller segments for either end.
Locking a segment 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()
system call. When enforcement-mode file and record locking is activated on a file
(see
chmod(2)),
future
creat(),
open(),
read(),
write(),
truncate(),
and
ftruncate()
system calls on the file are affected by the record locks in effect. File Share ReservationsFile share reservations are an advisory form of access control among
cooperating processes, on both local and remote machines.
They are most
commonly used by DOS or Windows emulators and DOS based NFS clients.
The
fcntl()
system call can be used to set file share reservations via the
F_SHARE
command. A share reservation is described by an fshare structure defined in
<sys/fcntl.h>
as follows:
struct fshare {
short f_access;
short f_deny;
long f_id;
}; The structure
fshare
describes the type of access
(f_access),
to be requested on the open file descriptor.
If the command succeeds it also
specifies what type of access to deny other processes
(f_deny),
A single process on the same file may hold several non-conflicting
reservations by specifying an identifier,
(f_id),
unique to the process with each share reservation request. Valid
f_access
values are: - R_RDACC
Set a file share reservation for read-only access. - R_WRACC
Set a file share reservation for write-only access. - R_RWACC
Set a file share reservation for read-write access.
Valid
f_deny
values are: - F_COMPAT
Set a file share reservation to compatibility mode. - F_RDDNY
Set a file share reservation to deny read access to other processes. - F_WRDNY
Set a file share reservation to deny write access to other processes. - F_RWDNY
Set a file share reservation to deny read and write access to other processes. - F_NODNY
Set a file share reservation to not deny read or write access to other
processes.
OplocksAn
oplock
is a type of caching hint used mostly by CIFS clients so they
may cache data locally.
This helps increase performance by not having to read data across a
network each time a file operation is performed.
The oplock guarantees that no other remote process is accessing the
file in a way that might lead to data inconsistencies. The following arguments are supported for oplocks. - F_SETOPLOCK
Requests an opportunistic lock reservation (oplock) on a file.
The supported oplock types are defined in
<sys/oplock.h>. - F_SETOPLOCKW
Requests an opportunistic lock reservation (oplock) on a file and will wait
(in other words, block) until the request may be granted. - F_REMOVEOPLOCK
Removes all oplocks by pid. - F_HAVEOPLOCK
Checks
to see if an oplock is present on a file.
The possible returns values
are one of the oplock types defined in
<sys/oplock.h>.
An oplock request is described by an
oplock
structure which is defined in
<sys/oplock.h>
as follows: struct oplock{
int64_t o_owner;
sysid_t o_member_id;
int64_t o_type;
sysid_t o_sysid;
pid_t o_pid;
int64_t o_flags;
int64_t o_retry;
int64_t o_timeout;
int64_t o_sig_val;
}; The structure
oplock
describes the details of the lock being requested on the opened file
descriptor.
If the command succeeds it also contains the
owner ID
(o_owner)
of the process as well as the type of oplock
(o_type)
being requested.
The
o_sysid
may also be specified.
The process ID
(o_pid)
is the requesting process with which to associate the oplock.
Optional flags
o_flags,
o_timeout,
and signal value
(o_sig_val)
may also be specified. The only field in this structure which must be assigned is
o_type.
The other fields are either optional or not used and should be
initialized to zero (0). The fields in the
oplock
structure are described here:
- o_owner
Owner type. Any integer; however, 0x8000 is reserved. - o_member_id
Member ID. Any unique integer of type
sysid_t. - o_type
Type of oplock.
May be one of these values:
- VFS_OPLOCK_NONE
Removes an oplock. - VFS_OPLOCK_SHARED
Request a shared oplock. - VFS_OPLOCK_EXCLUSIVE
Request an exclusive oplock. - VFS_OPLOCK_BATCH
Request a batch oplock.
(Requires CIFS stacked file system support)
- o_sysid
The system ID of the locking process.
This is an optional value. - o_pid
The process ID of the process that owns the oplock.
This does not need to be filled in by the application,
as this is done internally. - o_flags
This
field is not currently used and is here for future needs.
It is recommended this be initialized to zero (0). - o_retry
This field is the number of retries to gracefully request that an oplock be
broken.
After the number of retries are exhausted, then the oplock will be
removed without acknowledgment from the process that owns it. - o_timeout
This value represents the wait time in seconds that the kernel will wait
before re-sending the oplock break signal.
The total time that an application may
wait for an oplock is
(o_retry+1)
multiplied by
o_timeout
seconds. - o_sig_val
A value to be sent with signal to a process upon an oplock being broken.
Application UsageBecause in the future the external variable
errno
will be 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.
For example:
flk->l_type = F_RDLCK;
if (fcntl(fd, F_SETLK, flk) == -1)
if ((errno == EACCES) || (errno == EAGAIN))
/*
* section locked by another process,
* check for either EAGAIN or EACCES
* due to different implementations
*/
else if ...
/*
* check for other errors
*/ NETWORKING FEATURESNFSThe advisory record-locking capabilities of
fcntl()
are implemented throughout the network by the "network lock daemon" (see
lockd(1M)).
If the file server crashes and is rebooted,
the lock daemon attempts to recover all locks
associated with the crashed server.
If a lock cannot be reclaimed, the process that held the lock is issued a
SIGLOST
signal. Record locking, as implemented for NFS files, is only advisory. RETURN VALUEUpon successful completion,
the value returned depends on
cmd
as follows:
- F_ADVISE
Value of requested hint operation. - F_DUPFD
A new file descriptor. - F_GETFD
Value of close-on-exec flag (only the low-order bit is defined). - F_SETFD
Value other than -1. - F_GETFL
Value of file status flags and access modes. - F_SETFL
Value other than -1. - F_GETLK
Value other than -1. - F_SETLK
Value other than -1. - F_SETLKW
Value other than -1. - F_SETOPLOCK
Value other than -1. - F_SETOPLOCKW
Value other than -1. - F_HAVE_OPLOCK
Value other than -1. - F_REMOVE_OPLOCK
Value other than -1. - F_GETLK64
Value other than -1. - F_SETLK64
Value other than -1. - F_SETLKW64
Value other than -1. - F_GETOWN
Value of process or process group ID specified to receive
SIGURG
signals when out-of-band data is available. - F_SETOWN
Value other than -1. - F_GETTIMES
Value other than -1. - F_SETTIMES
Value other than -1. - F_SHARE
Value other than -1. - F_UNSHARE
Value other than -1.
Otherwise, a value of -1 is returned and
errno
is set to indicate the error. ERRORSfcntl()
fails if any of the following conditions occur:
- EACCES
cmd
is
F_SETLK,
the type of lock
(l_type)
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
(F_WRLCK)
and the segment of a file to be locked is already
read- or write-locked by another process. - EAGAIN
cmd
is
F_SETLK
or
F_SETLKW,
and the file is mapped in to virtual memory via the
mmap()
system call (see
mmap(2)). - EAGAIN
cmd
is
F_SHARE
and
f_access
conflicts with an existing
f_deny
share reservation. - EAGAIN
cmd
is
F_SETOPLOCK,
and this request conflicts with an existing byte lock or share reservation. - EBADF
fildes
is not a valid open file descriptor,
or was not opened for reading when setting a read lock,
or for writing when setting a write lock. - EBADF
cmd
arg is
F_SHARE,
and the
f_access
share reservation is for read or write access,
and the file descriptor is not a valid file descriptor open for reading. - EDEADLK
cmd
is
F_SETLKW,
when the lock is blocked by a lock from another process
and sleeping (waiting) for that lock to become free.
This causes a deadlock situation. - EFAULT
cmd
is either
F_GETLK,
F_SETLK,
or
F_SETLKW,
and
arg
points to an illegal address. - EFAULT
cmd
is either
F_SHARE
or
F_UNSHARE,
and
arg
points to an illegal address. - EFAULT
cmd
is either
F_SETOPLOCK,
F_SETOPLOCKW,
F_HAVEOPLOCK,
or
F_REMOVEOPLOCK,
and
arg
points to an illegal address. - EINTR
cmd
is
F_SETLKW
and the call was interrupted by a signal. - EINVAL
cmd
is
F_DUPFD
and
arg
is negative. - EINVAL
cmd
is
F_GETLK,
F_SETLK,
or
F_SETLKW,
and
arg
or the data it points to is not valid, or
fildes
refers to a file that does not support locking. - EINVAL
cmd
is not a valid command. - EINVAL
cmd
is
F_SETFL
and both
O_NONBLOCK
and
O_NDELAY
are specified. - EINVAL
cmd
is
F_SETOPLOCK
or
F_SETOPLOCKW
and the
o_type,
o_timeout,
or
o_retry
values are not valid. - EINVAL
cmd
is
F_SHARE
or
F_UNSHARE
and
arg
is invalid. - EINVAL
cmd
is
F_DUPFD
and
arg
is greater than or equal to the maximum number of file descriptors. - EMFILE
cmd
is
F_DUPFD
and the maximum number of file descriptors is currently open. - ENOLCK
cmd
is
F_SETLK
or
F_SETLKW,
the type of lock is a read or write lock,
and no more record locks are available
(too many file segments locked). - ENOLCK
cmd
is
F_SETLK
or
F_SETLKW,
the type of lock
(l_type)
is a read lock
(F_RDLCK)
or write lock
(F_WRLCK)
and the file is an NFS
file with access bits set for enforcement mode. - ENOLCK
cmd
is
F_GETLK,
F_SETLK,
or
F_SETLKW,
the file is an NFS
file, and a system error occurred on the remote node. - [ENOSYS]
ENOSYS
cmd
is
F_SETOPLOCK
or
F_SETOPLOCKW
and the
arg
is
VFS_OPLOCK_FILTER
which is currently defined but not supported. - ENOTSOCK
cmd
is
F_GETOWN
or
F_SETOWN,
and
fildes
does not refer to a socket. - EOVERFLOW
cmd
is
F_GETLK
and the blocking lock's starting offset or length
would not fit in the caller's structure. - EPERM
cmd
is
F_SETTIMES
and the user does not have superuser privilege. - EWOULDBLOCK
cmd
is
F_ADVISE
the hint is
FADV_WILLNEED
and VM has detected a blocking condition.
WARNINGSOplock support is release specific and as such is not guaranteed to be
supported in future releases and/or with the same interface.
HP reserves the right to change or remove oplock support at any time. AUTHORfcntl()
was developed by HP, AT&T and the University of California, Berkeley. SEE ALSOlockd(1M),
statd(1M),
chmod(2),
close(2),
creat(2),
creat64(2),
exec(2),
fadvise(2),
lockf(2),
open(2),
read(2),
truncate(2),
write(2),
fcntl(5). STANDARDS CONFORMANCEfcntl(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
|