fcntl, dup, or dup2 Subroutine

Purpose

Controls open file descriptors.

Library

Standard C Library (libc.a)

Berkeley compatibility library (libbsd.a) (for the fcntl subroutine)

Syntax

#include <fcntl.h>

int fcntl ( FileDescriptor, Command, Argument) int  FileDescriptor, Command, Argument;

#include <unistd.h>

int dup2( Old, New) int  Old, New;

int dup( FileDescriptor) int  FileDescriptor;

Description

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.

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 the FileDescriptor parameter refers to a shared memory object, the fcntl subroutine manages only the F_DUPFD, F_DUP2FD, F_GETFD, F_SETFD, F_GETFL, and F_CLOSEM commands.

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. However, these commands are valid only when the file descriptor refers to a terminal device or a socket.

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.

General Record Locking Information

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, openat, openx, openxat, open64, open64at, open64x, open64xat, 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:

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).

Parameters

Item Description
FileDescriptor Specifies an open file descriptor obtained from a successful call to the open subroutine, fcntl subroutine, pipe subroutine, or shm_open subroutine. File descriptors are small positive integers used (instead offile names) to identify files or a shared memory object.
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.

Duplicating File Descriptors

Item Description
F_DUPFD Returns a new file descriptor as follows:
  • Lowest-numbered available file descriptor greater than or equal to the Argument parameter
  • 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 flags (That is, both file descriptors share the same file status flags.)
  • The close-on-exec flag (FD_CLOEXEC bit) associated with the new file descriptor is cleared

Setting File-Descriptor Flags

Item Description
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:

O_APPEND
Set append mode.
O_NONBLOCK
No delay.

The file-access modes have the following values:

O_RDONLY
Open for reading only.
O_RDWR
Open for reading and writing.
O_WRONLY
Open for writing only.

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:
  • O_APPEND or FAPPEND
  • O_NDELAY or FNDELAY
  • O_NONBLOCK or FNONBLOCK
  • O_SYNC or FSYNC
  • FASYNC

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.

Setting File Locks

Item Description
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.
Item Description
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.

Setting Process ID

Item Description
F_GETOWN Gets the process ID or process group currently receiving SIGIO and SIGURG signals. Process groups are returned as negative values.
F_SETOWN Sets the process or process group to receive SIGIO and SIGURG signals. Process groups are specified by supplying a negative Argument value. Otherwise, the Argument parameter is interpreted as a process ID.

Closing File Descriptors

Item Description
F_CLOSEM Closes all file descriptors from FileDescriptor up to the number specified by the OPEN_MAX value.
Old Specifies an open file descriptor.
New Specifies an open file descriptor that is returned by the dup2 subroutine.

Compatibility Interfaces

The lockfx Subroutine

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 dup and dup2 Subroutines

The fcntl subroutine functions similar to the dup and dup2 subroutines, when used in the following way:

dup (FileDescriptor)

is equivalent to:

fcntl (FileDescriptor, F_DUPFD, 0)
dup2 (Old, New)

is equivalent to:

close (New);
fcntl(Old, F_DUPFD, New)

The dup and dup2 subroutines differ from the fcntl subroutine in the following ways:

Return Values

Upon successful completion, the value returned depends on the value of the Command parameter, as follows:

Item Description
Command Return Value
F_DUPFD A new file descriptor
F_GETFD The value of the flag (only the FD_CLOEXEC bit is defined)
F_SETFD A value other than -1
F_GETFL The value of file flags
F_SETFL A value other than -1
F_GETOWN The value of descriptor owner
F_SETOWN A value other than -1
F_GETLK A value other than -1
F_SETLK A value other than -1
F_SETLKW A value other than -1
F_CLOSEM A value other than -1.

If the fcntl subroutine fails, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes

The fcntl subroutine is unsuccessful if one or more of the following are true:

Item Description
EACCES The Command argument is F_SETLK; the type of lock is a shared or exclusive lock and the segment of a file to be locked is already exclusively-locked by another process, or 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.
EBADF The FileDescriptor parameter is not a valid open file descriptor.
EDEADLK The Command argument is F_SETLKW; the lock is blocked by some lock from another process and putting the calling process to sleep, waiting for that lock to become free would cause a deadlock.
ENOTTY The file descriptor does not refer to a terminal device or socket.
EMFILE The Command parameter is F_DUPFD, and the maximum number of file descriptors are currently open (OPEN_MAX).
EINVAL The Command parameter is F_DUPFD, and the Argument parameter is negative or greater than or equal to OPEN_MAX.
EINVAL An illegal value was provided for the Command parameter.
EINVAL An attempt was made to lock a fifo or pipe.
ESRCH The value of the Command parameter is F_SETOWN, and the process ID specified as the Argument parameter is not in use.
EINTR The Command parameter was F_SETLKW and the process received a signal while waiting to acquire the lock.
EOVERFLOW The Command parameter was F_GETLK and the block lock could not be represented in the flock structure.

The dup and dup2 subroutines fail if one or both of the following are true:

Item Description
EBADF The Old parameter specifies an invalid open file descriptor or the New parameter specifies a file descriptor that is out of range.
EMFILE The number of file descriptors exceeds the OPEN_MAX value or there is no file descriptor above the value of the New parameter.

If NFS is installed on the system, the fcntl subroutine can fail if the following is true:

Item Description
ETIMEDOUT The connection timed out.