NAME

fcntl − file control

SYNOPSIS

#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>

int fcntl (int fildes, int cmd, . . .  /∗ arg ∗/);

DESCRIPTION

fcntl provides for control over open files.  fildes is an open file descriptor [see intro(2)]. 

fcntl may take a third argument, arg, whose data type, value and use depend upon the value of cmd.  cmd specifies the operation to be performed by fcntl and may be one of the following:

F_DUPFD Return a new file descriptor with the following characteristics:

Lowest numbered available file descriptor greater than or equal to the integer value given as the third argument. 

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) as the original file. 

Shares any locks associated with the original file descriptor. 

Same file status flags (that is, both file descriptors share the same file status flags) as the original file. 

The close-on-exec flag [see F_GETFD] associated with the new file descriptor is set to remain open across exec(2) system calls. 

F_GETFD Get the close-on-exec flag associated with fildes. If the low-order bit is 0, the file will remain open across exec.  Otherwise, the file will be closed upon execution of exec. 

F_SETFD Set the close-on-exec flag associated with fildes to the low-order bit of the integer value given as the third argument (0 or 1 as above). 

F_GETFL Get fildes status flags. 

F_SETFL Set fildes status flags to the integer value given as the third argument.  Only certain flags can be set [see fcntl(5)]. 

F_SETOWN (M88000 only)
The argument is an int that if greater than zero refers to a process ID and if less than zero refers to a process-group ID which is the absolute value of the argument.  Set the process or process-group ID that will subsequently receive SIGIO or SIGURG signals for the socket referred to by the descriptor passed to fcntl to the value of that int.  This is identical to the ioctl commands FIOSETOWN and SIOCSPGRP. 

F_GETOWN (M88000 only)
The argument is ignored. Return the int value that is the process ID or the process-group ID that is receiving SIGIO or SIGURG signals for the socket referred to by the descriptor passed to fcntl.  This is identical to the ioctl commands FIOGETOWN and SIOCGPGRP. 

F_FREESP Free storage space associated with a section of the ordinary file fildes.  The section is specified by a variable of data type struct flock pointed to by the third argument arg.  The data type struct flock is defined in the <fcntl.h> header file [see fcntl(5)] and contains the following members: l_whence is 0, 1, or 2 to indicate that the relative offset l_start will be measured from the start of the file, the current position, or the end of the file, respectively.  l_start is the offset from the position specified in l_whence.  l_len is the size of the section.  An l_len of 0 frees up to the end of the file; in this case, the end of file (i.e., file size) is set to the beginning of the section freed.  Any data previously written into this section is no longer accessible. 

The following commands are used for record-locking.  Locks may be placed on an entire file or on segments of a file. 

F_SETLK Set or clear a file segment lock according to the flock structure that arg points to [see fcntl(5)].  The cmd F_SETLK is used to establish read (F_RDLCK) and write (F_WRLCK) locks, as well as remove either type of lock (F_UNLCK).  If a read or write lock cannot be set, fcntl will return 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, fcntl will block until the segment is free to be locked. 

F_GETLK If the lock request described by the flock structure that arg points to could be created, then the structure is passed back unchanged except that the lock type is set to F_UNLCK and the l_whence field will be set to SEEK_SET. 

If a lock is found that would prevent this lock from being created, then the structure is overwritten with a description of the first lock that is preventing such a lock from being created.  The structure also contains the process ID and the system ID of the process holding the lock. 

This command never creates a lock; it tests whether a particular lock could be created. 

F_RSETLK Used by the network lock daemon, lockd(3N), to communicate with the NFS server kernel to handle locks on NFS files. 

F_RSETLKW Used by the network lock daemon, lockd(3N), to communicate with the NFS server kernel to handle locks on NFS files. 

F_RGETLK Used by the network lock daemon, lockd(3N), to communicate with the NFS server kernel to handle locks on NFS files. 

A read lock prevents any process from write locking the protected area.  More than one read lock may 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 process from read locking or write locking the protected area.  Only one write lock and no read locks 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 flock structure describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len), process ID (l_pid), and system ID (l_sysid) of the segment of the file to be affected.  The process ID and system ID fields are used only with the F_GETLK cmd to return the values for a blocking lock.  Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file.  A lock may be set to always extend to the end of file by setting l_len to 0.  If such a lock also has l_whence and l_start set to 0, the whole file will be locked.  Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments at either end.  Locking a segment that is 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(2) system call. 

When mandatory file and record locking is active on a file [see chmod(2)], creat(2), open(2), read(2) and write(2) system calls issued on the file will be affected by the record locks in effect. 

fcntl will fail if one or more of the following are true:

EACCES cmd is F_SETLK, the type of lock (l_type) is a read lock (F_RDLCK) 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_FREESP, the file exists, mandatory file/record locking is set, and there are outstanding record locks on the file. 

EAGAIN cmd is F_SETLK or F_SETLKW and the file is currently being mapped to virtual memory via mmap [see mmap(2)]. 

EBADF fildes is not a valid open file descriptor. 

EBADF cmd is F_SETLK or F_SETLKW, the type of lock (l_type) is a read lock (F_RDLCK), and fildes is not a valid file descriptor open for reading. 

EBADF cmd is F_SETLK or F_SETLKW, the type of lock (l_type) is a write lock (F_WRLCK), and fildes is not a valid file descriptor open for writing. 

EBADF cmd is F_FREESP, and fildes is not a valid file descriptor open for writing. 

EDEADLK cmd is F_SETLKW, the lock is blocked by some lock from another process, and if fcntl blocked the calling process waiting for that lock to become free, a deadlock would occur. 

EDEADLK cmd is F_FREESP, mandatory record locking is enabled, O_NDELAY and O_NONBLOCK are clear and a deadlock condition was detected. 

EFAULT cmd is F_FREESP and the value pointed to by the third argument arg resulted in an address outside the process’s allocated address space. 

EFAULT cmd is F_GETLK, F_SETLK or F_SETLKW and the value pointed to by the third argument resulted in an address outside the program address space. 

EINTR A signal was caught during execution of the fcntl system call. 

EIO An I/O error occurred while reading from or writing to the file system. 

EMFILE cmd is F_DUPFD and the number of file descriptors currently open in the calling process is the configured value for the maximum number of open file descriptors allowed each user. 

EINVAL cmd is F_DUPFD and the third argument is either negative, or greater than or equal to the configured value for the maximum number of open file descriptors allowed each user. 

EINVAL cmd is F_GETOWN or F_SETOWN and the fildes is not a STREAM device. 

EINVAL cmd is F_SETOWN and the third argument is not a valid process ID or the negative of a valid process-group ID . 

EINVAL cmd is not a valid value. 

EINVAL cmd is F_GETLK, F_SETLK, or F_SETLKW and the third argument or the data it points to is not valid, or fildes refers to a file that does not support locking. 

ENOLCK cmd is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more record locks available (too many file segments locked) because the system maximum has been exceeded. 

ENOLINK fildes is on a remote machine and the link to that machine is no longer active. 

ENOLINK cmd is F_FREESP, the file is on a remote machine, and the link to that machine is no longer active. 

EOVERFLOW cmd is F_GETLK and the process ID of the process holding the requested lock is too large to be stored in the l_pid field. 

SEE ALSO

close(2), creat(2), dup(2), exec(2), fork(2), open(2), pipe(2), fcntl(5) The "File and Record Locking" chapter

DIAGNOSTICS

On success, fcntl returns a value that depends on cmd:

F_DUPFD A new file descriptor. 

F_GETFD Value of flag (only the low-order bit is defined).  The return value will not be negative. 

F_SETFD Value other than −1. 

F_FREESP Value of 0. 

F_GETFL Value of file status flags.  The return value will not be negative. 

F_SETFL Value other than −1. 

F_GETLK Value other than −1. 

F_SETLK Value other than −1. 

F_SETLKW Value other than −1. 

On failure, fcntl returns −1 and sets errno to indicate the error. 

NOTES

In the future, the variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process.  Therefore, portable application programs should expect and test for either value.