fcntl() -- control open file descriptors

SYNOPSIS

#include <sys/types.h>

#include <unistd.h>

#include <fcntl.h>

int fcntl(int fildes, int cmd, ...);

struct flock {
	short l_type;
	short l_whence;
	off_t l_start;
	off_t l_len;
	pid_t l_pid;
};

struct flock64 {
	short l_type;
	short l_whence;
	off64_t l_start;
	off64_t l_len;
	pid_t l_pid;
};

DESCRIPTION

The fcntl() function provides control of open file descriptors.

The following commands are supported for all file types:

F_DUPFD

Return a new file descriptor which is the lowest numbered available (that is, not already open) file descriptor greater than or equal to the specified argument, which is of type int The new file descriptor refers to the same open file description as the original file descriptor, and shares any locks. The FD_CLOEXEC flag associated with the new file descriptor is cleared to keep the file open across calls to one of the exec() family of functions. The return value is the new file descriptor on success, or -1 on error.

F_SETFD

Set the file descriptor flags for the specified file descriptor. The argument is the new set of flags, as a variable of type int. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. The return value is 0 on success, or -1 on error. The following file descriptor flags may be set. Any additional bits set from the flags specified for F_GETFD are ignored. If any bits not defined here are specified, behavior is undefined.

FD_CLOEXEC: If set, the file descriptor is closed when one of the exec() family of functions is called. If not set, the file descriptor is inherited by the new process image.

F_GETFD

Get the file descriptor flags for the specified file descriptor. This command takes no argument. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file. The return value is the current file descriptor flags on success, or -1 on error. In addition to the flags specified for F_SETFD, the following flags may be returned.

FD_MANDATORYLOCK: Mandatory locking is enabled for the file referred to by the specified file descriptor.
FD_ADVISORYLOCK: Advisory locking is enabled for the file referred to by the specified file descriptor.
FD_DIRECTORY: The specified file descriptor refers to a directory.

F_SETFL

Set the file status flags for the specified file descriptor. The argument is the new set of flags, as a variable of type int. These flags are as specified for the oflag argument to open(), along with the additional values specified later. Bits corresponding to the file access mode and any other oflag bits not listed here are ignored. If any bits not defined here or in open() are set, behavior is undefined. The return value is 0 on success, or -1 on error. The following file status flags can be changed with F_SETFL:

O_APPEND: Valid only for file descriptors that refer to regular files. The file pointer is moved to the end of the file before each write.
O_ASYNC: Valid only for file descriptors that refer to sockets and communications ports. If enabled for a file descriptor, and an owning process/process group has been specified with the F_SETOWN command to fcntl(), then a SIGIO signal is sent to the owning process/process group when input is available on the file descriptor.
O_BINARY: Sets the file descriptor to binary mode. See PORTING ISSUES for more information.
O_LARGEFILE: Sets the file descriptor to indicate a large-file aware application.
O_NDELAY: Sets the file descriptor to no-delay mode.
O_NONBLOCK: Sets the file descriptor to non-blocking mode. The distinction between non-blocking mode and no-delay mode is relevant only for a few types of special files such as pipes and FIFOs. Refer to read() and write() for more information.
O_SYNC: Sets the file descriptor to synchronous-write mode. Writes do not return until file buffers have been flushed to disk.
O_TEXT: Sets the file descriptor to text mode. See PORTING ISSUES for more information.
FAPPEND: A synonym for O_APPEND.
FASYNC: A synonym for O_ASYNC.
FNDELAY: A synonym for O_NDELAY.

F_GETFL

Get the file status flags and file access modes for the specified file descriptor. These flags are as specified for the oflag argument to open(), along with the additional values described for F_SETFL. File status flags 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 return value is the current file status flags and file access modes on success, or -1 on error. The following macros can be used to access fields of the return value:

O_ACCMODE: Extracts the access-mode field, which is one of O_RDONLY, O_RDWR, or O_WRONLY. Refer to the documentation for open() for more information.

The following commands are supported only for sockets and communication ports:

F_SETOWN

Sets the owning process ID or process group ID for the specified file descriptor. The owning process or process group can receive SIGURG signals for out-of-band data or sockets and/or SIGIO signals for readable data on sockets or communications ports. The argument is the process ID or the negative of the process group ID for the owner, as a variable of type pid_t. The return value is 0 on success, or -1 on error.

To receive SIGURG signals, the process should establish a SIGURG handler prior to setting ownership of the file descriptor. A SIGURG signal is generated whenever out-of-band data is received.

To receive SIGIO signals, the process should establish a SIGIO handler prior to setting ownership of the file descriptor, and then must enable O_ASYNC with the F_SETFL command to fcntl(). A SIGIO signal is generated whenever there is data to be read on the file descriptor.

F_GETOWN

Gets the owning process ID or process group ID for the specified file descriptor. The return value is the owner ID on success, or -1 on error. Behavior is undefined if no owner has been established with F_SETOWN.

The following commands are used for file locking. Locks may be advisory or mandatory; refer to PORTING ISSUES for more information. These command are supported only for regular files:

F_GETLK: Get the first lock which blocks a lock description for the file to which the specified file descriptor refers. The argument is a pointer to a variable of type struct flock, described later. The structure is overwritten with the returned lock information. If no lock is found that would prevent this lock from being created, then the structure is unchanged except for the lock type, which is set to F_UNLCK. The return value is 0 on success, or -1 or error.
F_GETLK64: Equivalent to F_GETLK, but takes a struct flock64 argument rather than a struct flock argument.
F_SETLK: Set or clear a file segment lock for the file to which the specified file descriptor refers. The argument is a pointer to a variable of type struct flock, described later. F_SETLK is used to establish shared (or read) locks (F_RDLCK) or exclusive (or write) locks (F_WRLCK), as well as to remove either type of lock (F_UNLCK). The return value is 0 on success, or -1 on error. If the lock cannot be immediately obtained, fcntl() returns -1 with errno set to EACCES.
F_SETLK64: Equivalent to F_SETLK, but takes a struct flock64 argument rather than a struct flock argument.
F_SETLKW: This command is the same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the thread waits until the request can be satisfied. If a signal that is to be caught is received while fcntl() is waiting for a region, fcntl() is interrupted. Upon return from the signal handler, fcntl() returns -1 with errno set to EINTR, and the lock operation is not done.
F_SETLKW64: Equivalent to F_SETLKW, but takes a struct flock64 argument rather than a struct flock argument.

When a shared lock is set on a segment of a file, other processes can 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 is not opened with write access.

The flock and flock64 structure contains the following fields:

l_type

Specifies the type of lock request. Valid settings are:

F_RDLCK: Create a shared lock.
F_WRLCK: Create an exclusive lock.
F_UNLCK: Remove a lock.

l_whence

Specifies the starting offset of the lock segment in the file. Valid settings are:

SEEK_SET: l_start specifies a position relative to the start of the file.
SEEK_CUR: l_start specifies a position relative to the current file offset.
SEEK_END: l_start specifies a position relative to the end of the file.

On a successful return from an F_GETLK or F_GETLK64 command for which a lock was found, the l_whence field is set to SEEK_SET.

l_start

Specifies the relative offset of the start of the lock segment. This setting is used with l_whence to determine the actual start position.

l_len

Specifies the number of consecutive bytes in the lock segment. This value may be negative.

l_pid

On a successful return from an F_GETLK or F_GETLK64 command for which a lock was found, this field contains the process ID of the process holding the lock.

If l_len is positive, the affected area 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 end beyond the current end of a file, but must not be negative relative to the beginning of the file. Setting l_len to 0 sets a lock that can extend to the largest possible value of the file offset for that file. If such a lock also has l_start set to 0 and l_whence set to SEEK_SET, the whole file is locked.

There can be at most one type of lock set of each byte in the file. Before a successful return from an F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 request when the calling process has previously existing locks on bytes in the region specified by the request, the previous lock type for each byte in the specified region is replaced by the new lock type. As specified earlier, an F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 request fails or blocks, respectively, when another process has existing locks on bytes in the specified region and the type of any of those locks conflicts with the type specified in the request.

All locks associated with a file for a given process 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 created using fork().

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, fcntl() returns -1 with errno set to EDEADLK.

PARAMETERS

fildes: Is the file descriptor to which the control is applied.
cmd: Is one of the available commands, as listed in the DESCRIPTION section.
...: Represents arguments to cmd, as specified in the description of cmd.

RETURN VALUES

If successful, fcntl() returns a value as described for each command in the DESCRIPTION section. On failure, it returns -1 and sets errno to one of the following values:

EACCES

The cmd parameter is F_SETLK or F_SETLK64; the type of lock is a shared (F_RDLCK) or exclusive (F_WRLCK) 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 fildes parameter is not a valid open file descriptor.

The cmd parameter is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64, the type of lock is a shared lock (F_RDLCK) and fildes is not a valid file descriptor open for reading.

The cmd parameter is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64, the type of lock is an exclusive lock (F_WRLCK) and fildes is not a valid file descriptor open for writing.

EDEADLK

The cmd parameter is F_SETLKW or F_SETLKW64, 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.

EINTR

The cmd parameter is F_SETLKW or F_SETLKW64 and the function was interrupted by a signal.

EINVAL

The cmd parameter is not one of the values listed in the DESCRIPTION section.

The cmd parameter is F_DUPFD and the supplied argument is negative or greater than or equal to OPEN_MAX.

The cmd parameter is F_SETFD or F_SETFL and the supplied argument does not specify valid flags for fildes.

The cmd parameter is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 and either the supplied argument is invalid, or fildes refers to a file that does not support locking.

The cmd parameter is F_SETOWN and the supplied argument does not specify the calling process' process ID or process group.

EISDIR

The cmd parameter is F_GETLK, F_GETLK64, F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64, and fildes refers to a directory.

EMFILE

The cmd parameter is F_DUPFD and OPEN_MAX file descriptors are currently open in the calling process, or no file descriptors greater than or equal to the supplied argument are available.

ENOLCK

The cmd parameter is F_SETLK, F_SETLK64, F_SETLKW, or F_SETLKW64 and the number of locked regions available in the system would be exceeded by the request.

EOVERFLOW

The cmd parameter is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, if l_len is non-zero, the largest offset of any byte in the requested segment cannot be represented correctly in an object of type off_t.

CONFORMANCE

UNIX 98, with exceptions. Large File Summit, 1996.

MULTITHREAD SAFETY LEVEL

Async-signal-safe.

PORTING ISSUES

If a file descriptor is set to text mode, then carriage-return/line-feed pairs are mapped to single line-feeds on input, and single line-feeds are mapped to carriage-return/line-feed pairs on output. Refer to File Management in the Windows Concepts chapter of the PTC MKS Toolkit UNIX to Windows Porting Guide.

Standard locks set with the fcntl() F_SETLK/F_SETLK64/F_SETLKW/F_SETLKW64 commands apply only to the local system. Locks are, by default, advisory. The NuTCRACKER Platform also supports a form of mandatory locking on 8.1/2012R2/10/2016/2019/11/2022. If the S_ISGID access mode bit is set for a file, and S_IXGRP is not set, then the NuTCRACKER Platform enables mandatory locking for the file using Win32 APIs. Mandatory locks are not inherited across exec(). Refer to chmod() and struct stat for more information on setting mode bits for a file.

The NuTCRACKER Platform also supports an advisory locking mode that uses the native Win32 locking APIs (LockFileEx() on 8.1/2012R2/10/2016/2019/11/2022). This mode can be set with the _NC_SET_NT_LIMITED_LOCKING parameter to _NutConf(), or via the NUT_NT_LIMITED_LOCKING environment variable. This mode supports network locking, but does not have normal UNIX semantics (for example, locks cannot be read back, lock operations cannot be interrupted, and locks are not inherited across exec()). Refer to _NutConf(), and to Environment Variables in the PTC MKS Toolkit UNIX to Windows Porting Guide for more information.

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

fcntl()
control open file descriptors

Function