 |
James Thornton |
| Internet Business Consultant |
| Home | Blog | Bio | Projects | Contact | Latest Blog (new site): How to Get to Genius |
|---|
|
Namefcntl - manipulate file descriptorSynopsis#include <unistd.h>#include <fcntl.h> int fcntl(int fd, int cmd);int fcntl(int fd, int cmd, long arg);int fcntl(int fd, int cmd, struct flock *lock); Descriptionfcntl performs one of various miscellaneous operations on fd. The operation in question is determined by cmd.Handling close-on-exec
The file status flagsA file descriptor has certain associated flags, initialized by open(2) and possibly modified by fcntl(2) . The flags are shared between copies (made with dup(2) , fork(2) , etc.) of the same file descriptor.The flags and their semantics are described in open(2) .
Advisory lockingF_GETLK, F_SETLK and F_SETLKW are used to acquire, release, and test for the existence of record locks (also known as file-segment or file-region locks). The third argument lock is a pointer to a structure that has at least the following fields (in unspecified order).
struct flock {
...
short l_type; /* Type of lock: F_RDLCK,
F_WRLCK, F_UNLCK */
short l_whence; /* How to interpret l_start:
SEEK_SET, SEEK_CUR, SEEK_END */
off_t l_start; /* Starting offset for lock */
off_t l_len; /* Number of bytes to lock */
pid_t l_pid; /* PID of process blocking our lock
(F_GETLK only) */
...
};
The l_whence, l_start, and l_len fields of this structure specify the range of bytes we wish to lock. l_start is the starting offset for the lock, and is interpreted relative to either: the start of the file (if l_whence is SEEK_SET); the current file offset (if l_whence is SEEK_CUR); or the end of the file (if l_whence is SEEK_END). In the final two cases, l_start can be a negative number provided the offset does not lie before the start of the file. l_len is a non-negative integer (but see the NOTES below) specifying the number of bytes to be locked. Bytes past the end of the file may be locked, but not bytes before the start of the file. Specifying 0 for l_len has the special meaning: lock all bytes starting at the location specified by l_whence and l_start through to the end of file, no matter how large the file grows. The l_type field can be used to place a read (F_RDLCK) or a write (F_WDLCK) lock on a file. Any number of processes may hold a read lock (shared lock) on a file region, but only one process may hold a write lock (exclusive lock). An exclusive lock excludes all other locks, both shared and exclusive. A single process can hold only one type of lock on a file region; if a new lock is applied to an already-locked region, then the existing lock is converted to the the new lock type. (Such conversions may involve splitting, shrinking, or coalescing with an existing lock if the byte range specified by the new lock does not precisely coincide with the range of the existing lock.)
In order to place a read lock, fd must be open for reading. In order to place a write lock, fd must be open for writing. To place both types of lock, open a file read-write. As well as being removed by an explicit F_UNLCK, record locks are automatically released when the process terminates or if it closes any file descriptor referring to a file on which locks are held. This is bad: it means that a process can lose the locks on a file like /etc/passwd or /etc/mtab when for some reason a library function decides to open, read and close it. Record locks are not inherited by a child created via fork(2) , but are preserved across an execve(2) . Because of the buffering performed by the stdio(3) library, the use of record locking with routines in that package should be avoided; use read(2) and write(2) instead.
Mandatory locking(Non-POSIX.) The above record locks may be either advisory or mandatory, and are advisory by default. To make use of mandatory locks, mandatory locking must be enabled (using the "-o mand" option to mount(8) ) for the file system containing the file to be locked and enabled on the file itself (by disabling group execute permission on the file and enabling the set-GID permission bit).Advisory locks are not enforced and are useful only between cooperating processes. Mandatory locks are enforced for all processes.
Managing signalsF_GETOWN, F_SETOWN, F_GETSIG and F_SETSIG are used to manage I/O availability signals:
Using these mechanisms, a program can implement fully asynchronous I/O without using select(2) or poll(2) most of the time. The use of O_ASYNC, F_GETOWN, F_SETOWN is specific to BSD and Linux. F_GETSIG and F_SETSIG are Linux-specific. POSIX has asynchronous I/O and the aio_sigevent structure to achieve similar things; these are also available in Linux as part of the GNU C Library (Glibc).
LeasesF_SETLEASE and F_GETLEASE (Linux 2.4 onwards) are used (respectively) to establish and retrieve the current setting of the calling process's lease on the file referred to by fd. A file lease provides a mechanism whereby the process holding the lease (the "lease holder") is notified (via delivery of a signal) when another process (the "contestant") tries to open(2) or truncate(2) that file.
A process may hold only one type of lease on a file. Leases may only be taken out on regular files. An unprivileged process may only take out a lease on a file whose UID matches the file system UID of the process.
When the contestant performs an open() or truncate() that conflicts with a lease established via F_SETLEASE, the system call is blocked by the kernel (unless the O_NONBLOCK flag was specified to open(), in which case it returns immediately with the error EWOULDBLOCK). The kernel then notifies the lease holder by sending it a signal (SIGIO by default). The lease holder should respond to receipt of this signal by doing whatever cleanup is required in preparation for the file to be accessed by another process (e.g., flushing cached buffers) and then remove its lease by performing an F_SETLEASE command specifying arg as F_UNLCK. If the lease holder fails to release the lease within the number of seconds specified in /proc/sys/fs/lease-break-time and the contestant's system call remains blocked (i.e., the contestant did not specify O_NONBLOCK on its open() call, and the system call was not interrupted by a signal handler) then the kerrnel forcibly breaks the lease holder's lease. Once the lease has been voluntarily or forcibly removed, and assuming the contestant has not unblocked its system call, the kernel permits the contestant's system call to proceed. The default signal used to notify the lease holder is SIGIO, but this can be changed using the F_SETSIG command to fcntl (). If a F_SETSIG command is performed (even one specifying SIGIO), and the signal handler is established using SA_SIGINFO, then the handler will receive a siginfo_t sructure as its second argument, and the si_fd field of this argument will hold the descriptor of the leased file that has been accessed by another process. (This is useful if the caller holds leases against multiple files). File and directory change notification
Return ValueFor a successful call, the return value depends on the operation:
On error, -1 is returned, and errno is set appropriately. Errors
NotesThe errors returned by dup2 are different from those returned by F_DUPFD.Since kernel 2.0, there is no interaction between the types of lock placed by flock(2) and fcntl(2) . POSIX 1003.1-2001 allows l_len to be negative. (And if it is, the interval described by the lock covers bytes l_start+l_len up to and including l_start-1.) However, for current kernels the Linux system call returns EINVAL in this situation. Several systems have more fields in struct flock such as e.g. l_sysid. Clearly, l_pid alone is not going to be very useful if the process holding the lock may live on a different machine.
Conforming toSVr4, SVID, POSIX, X/OPEN, BSD 4.3. Only the operations F_DUPFD, F_GETFD, F_SETFD, F_GETFL, F_SETFL, F_GETLK, F_SETLK and F_SETLKW are specified in POSIX.1. F_GETOWN and F_SETOWN are BSDisms not supported in SVr4; F_GETSIG and F_SETSIG are specific to Linux. F_NOTIFY, F_GETLEASE, and F_SETLEASE are Linux specific. (Define the _GNU_SOURCE macro before including <fcntl.h> to obtain these definitions.) The flags legal for F_GETFL/F_SETFL are those supported by open(2) and vary between these systems; O_APPEND, O_NONBLOCK, O_RDONLY, and O_RDWR are specified in POSIX.1. SVr4 supports several other options and flags not documented here.SVr4 documents additional EIO, ENOLINK and EOVERFLOW error conditions. See Alsodup2(2) , flock(2) , lockf(3) , open(2) , socket(2)See also locks.txt, mandatory.txt, and dnotify.txt in /usr/src/linux/Documentation.
|
|
James Thornton, jamesthornton.com>Services: Online Marketing Solution |
Electric Speed: Software Programming |