Controls open file descriptors.
int fcntl ( FileDescriptor, Command, Argument)
int FileDescriptor,
Command, Argument;
int dup2( Old,
New)
int Old,
New;
int dup( FileDescriptor)
int FileDescriptor;
The fcntl subroutine performs controlling operations on the open file specified by the FileDescriptor parameter. If Network File System (NFS) is installed on your system, the open file can reside on another node. The fcntl subroutine is used to:
The fcntl subroutine can provide the same functions as the dup and dup2 subroutines.
A lock is either an enforced or advisory lock and either a read or a write lock.
Attention: Buffered I/O does not work properly when used with file locking. Do not use the standard I/O package routines on files that are going to be locked.
For a lock to be an enforced lock, the Enforced Locking attribute of the file must be set; for example, the S_ENFMT bit must be set, but the S_IXGRP, S_IXUSR, and S_IXOTH bits must be clear. Otherwise, the lock is an advisory lock. A given file can have advisory or enforced locks, but not both. The description of the sys/mode.h file includes a description of file attributes.
When a process holds an enforced lock on a section of a file, no other process can access that section of the file with the read or write subroutine. In addition, the open (open, openx, open64, creat, or creat64 Subroutine) and ftruncate subroutines cannot truncate the locked section of the file, and the fclear (fclear or fclear64 Subroutine) subroutine cannot modify the locked section of the file. If another process attempts to read or modify the locked section of the file, the process either sleeps until the section is unlocked or returns with an error indication.
When a process holds an advisory lock on a section of a file, no other process can lock that section of the file (or an overlapping section) with the fcntl subroutine. (No other subroutines are affected.) As a result, processes must voluntarily call the fcntl subroutine in order to make advisory locks effective.
When a process holds a read lock on a section of a file, other processes can also set read locks on that section or on subsets of it. Read locks are also called shared locks.
A read lock prevents any other process from setting a write lock on any part of the protected area. If the read lock is also an enforced lock, no other process can modify the protected area.
The file descriptor on which a read lock is being placed must have been opened with read access.
When a process holds a write lock on a section of a file, no other process can set a read lock or a write lock on that section. Write locks are also called exclusive locks. Only one write lock and no read locks can exist for a specific section of a file at any time.
If the lock is also an enforced lock, no other process can read or modify the protected area.
The following general rules about file locking apply:
Note: Deadlocks due to file locks in a distributed system are not always detected. When such deadlocks can possibly occur, the programs requesting the locks should set time-out timers.
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 extend to the end of the file by setting the l_len field to 0. If such a lock also has the l_start and l_whence fields set to 0, the whole file is locked. The l_len, l_start, and l_whence locking fields are part of the flock structure.
Note: The following description applies to AIX 4.3 and later releases.
When an application locks a region of a file using the 32 bit locking interface (F_SETLK), and the last byte of the lock range includes MAX_OFF (2 Gb - 1), then the lock range for the unlock request will be extended to include MAX_END (2 ^ ^ 63 - 1).
| FileDescriptor | Specifies an open file descriptor obtained from a successful call to the open, fcntl, or pipe (pipe Subroutine) subroutine. File descriptors are small positive integers used (instead of file names) to identify files. |
| Argument | Specifies a variable whose value sets the function specified by the Command parameter. When dealing with file locks, the Argument parameter must be a pointer to the FLOCK structure. |
| Command | Specifies the operation performed by the fcntl subroutine. The fcntl subroutine can duplicate open file descriptors, set file-descriptor flags, set file descriptor locks, set process IDs, and close open file descriptors. |
| F_GETFD | Gets the close-on-exec flag (FD_CLOEXEC bit) that is associated with the file descriptor specified by the FileDescriptor parameter. The Argument parameter is ignored. File descriptor flags are associated with a single file descriptor, and do not affect others associated with the same file. |
| F_SETFD | Assigns the value of the Argument parameter to the close-on-exec flag (FD_CLOEXEC bit) that is associated with the FileDescriptor parameter. If the FD_CLOEXEC flag value is 0, the file remains open across any calls to exec subroutines; otherwise, the file will close upon the successful execution of an exec subroutine. |
| F_GETFL | Gets the file-status flags and file-access modes for the open file
description associated with the file descriptor specified by the
FileDescriptor parameter. The open file description is set
at the time the file is opened and applies only to those file descriptors
associated with that particular call to the file. This open file
descriptor does not affect other file descriptors that refer to the same file
with different open file descriptions.
The file-status flags have the following values: The file-access modes have the following values:
The file access flags can be extracted from the return value using the O_ACCMODE mask, which is defined in the fcntl.h file. |
| F_SETFL | Sets the file status flags from the corresponding bits specified by the
Argument parameter. The file-status flags are set for the
open file description associated with the file descriptor specified by the
FileDescriptor parameter. The following flags may be
set:
The O_NDELAY and O_NONBLOCK flags affect only operations against file descriptors derived from the same open subroutine. In BSD, these operations apply to all file descriptors that refer to the object. |
| F_GETLK | Gets information on the first lock that blocks the lock described in the flock structure. The Argument parameter should be a pointer to a type struct flock, as defined in the flock.h file. The information retrieved by the fcntl subroutine overwrites the information in the struct flock pointed to by the Argument parameter. If no lock is found that would prevent this lock from being created, the structure is left unchanged, except for lock type (l_type) which is set to F_UNLCK. |
| F_SETLK | Sets or clears a file-segment lock according to the lock description pointed to by the Argument parameter. The Argument parameter should be a pointer to a type struct flock, which is defined in the flock.h file. The F_SETLK option is used to establish read (or shared) locks (F_RDLCK), or write (or exclusive) locks (F_WRLCK), as well as to remove either type of lock (F_UNLCK). The lock types are defined by the fcntl.h file. If a shared or exclusive lock cannot be set, the fcntl subroutine returns immediately. |
| F_SETLKW | Performs the same function as the F_SETLK option unless a read or write lock is blocked by existing locks, in which case the process sleeps until the section of the file is free to be locked. If a signal that is to be caught is received while the fcntl subroutine is waiting for a region, the fcntl subroutine is interrupted, returns a -1, sets the errno global variable to EINTR. The lock operation is not done. |
Note: F_GETLK64, F_SETLK64, and F_SETLKW64 apply to AIX 4.2 and later releases.
| F_GETLK64 | Gets information on the first lock that blocks the lock described in the flock64 structure. The Argument parameter should be a pointer to an object of the type struct flock64, as defined in the flock.h file. The information retrieved by the fcntl subroutine overwrites the information in the struct flock64 pointed to by the Argument parameter. If no lock is found that would prevent this lock from being created, the structure is left unchanged, except for lock type (l_type) which is set to F_UNLCK. |
| F_SETLK64 | Sets or clears a file-segment lock according to the lock description pointed to by the Argument parameter. The Argument parameter should be a pointer to a type struct flock64, which is defined in the flock.h file. The F_SETLK option is used to establish read (or shared) locks (F_RDLCK), or write (or exclusive) locks (F_WRLCK), as well as to remove either type of lock (F_UNLCK). The lock types are defined by the fcntl.h file. If a shared or exclusive lock cannot be set, the fcntl subroutine returns immediately. |
| F_SETLKW64 | Performs the same function as the F_SETLK option unless a read or write lock is blocked by existing locks, in which case the process sleeps until the section of the file is free to be locked. If a signal that is to be caught is received while the fcntl subroutine is waiting for a region, the fcntl subroutine is interrupted, returns a -1, sets the errno global variable to EINTR. The lock operation is not done. |
The fcntl subroutine functions similar to the lockfx subroutine, when the Command parameter is F_SETLK, F_SETLKW, or F_GETLK, and when used in the following way:
fcntl (FileDescriptor, Command, Argument)
is equivalent to:
lockfx (FileDescriptor, Command, Argument)
The fcntl subroutine functions similar to the dup and dup2 subroutines, when used in the following way:
dup (FileDescriptor)
fcntl (FileDescriptor, F_DUPFD, 0)
dup2 (Old, New)
close (New); fcntl(Old, F_DUPFD, New)
The dup and dup2 subroutines differ from the fcntl subroutine in the following ways:
Upon successful completion, the
value returned depends on the value of the Command parameter, as
follows:
If the fcntl subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.
The fcntl subroutine is
unsuccessful if one or more of the following are true:
The dup and
dup2 subroutines fail if one or both of the following are true:
If NFS is installed on the system,
the fcntl subroutine can fail if the following is true:
| ETIMEDOUT | The connection timed out. |
These subroutines are part of Base Operating System (BOS) Runtime.
If FileDescriptor refers to a terminal device or socket, then asynchronous I/O facilities can be used. These facilities are normally enabled by using the ioctl subroutine with the FIOASYNC, FIOSETOWN, and FIOGETOWN commands. However, a BSD-compatible mechanism is also available if the application is linked with the libbsd.a library.
When using the libbsd.a library, asynchronous I/O is enabled by using the F_SETFL command with the FASYNC flag set in the Argument parameter. The F_GETOWN and F_SETOWN commands get the current asynchronous I/O owner and set the asynchronous I/O owner.
All applications containing the fcntl subroutine must be complied with _BSD set to a specific value. Acceptable values are 43 and 44. In addition, all socket applications must include the BSD libbsd.a library.
The close (close Subroutine) subroutine, execl, excecv, execle, execve, execlp, execvp, or exect (exec: execl, execle, execlp, execv, execve, execvp, or exect Subroutine) subroutines, fork (fork, f_fork, or vfork Subroutine) subroutine, ioctl or ioctlx (ioctl, ioctlx, ioctl32, or ioctl32x Subroutine) subroutine, lockf (lockfx, lockf, flock, or lockf64 Subroutine) subroutine, open, openx, or creat (open, openx, open64, creat, or creat64 Subroutine) subroutines, read subroutine, write subroutine.
Files, Directories, and File Systems for Programmers in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.