fcntl(2)

fcntl -- file control

Synopsis

   #include <sys/types.h>
   #include <sys/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_DUP2

Will atomically close fildes2 and replace it with a duplicate of fildes. The operation can be invoked as fcntl(fildes, F_DUP2, fildes2). (See dup2(3C).)

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_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 sys/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. F_FREESP is only supported with an l_len of 0, and frees up to the end of the file. The end of file (that is, file size) is set to the beginning of the section freed. If the beginning of the segment specified by the flock structure is beyond the current end of the file, then the file size is increased. Any data previously written into this section is no longer accessible.

F_FREESP64

Free storage space associated with a section of the ordinary file fildes. The section is specified by a variable of data type struct flock64 pointed to by the third argument arg. The data type struct flock64 is defined in the sys/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. F_FREESP64 is only supported with an l_len of 0, and frees up to the end of the file. The end of file (that is, file size) is set to the beginning of the section freed. If the beginning of the segment specified by the flock structure is beyond the current end of the file, then the file size is increased. Any data previously written into this section is no longer accessible.

F_GETOWN

If fildes refers to a socket, get the process or process group id specified to receive SIGURG signals when out-of-band data is available. Positive values indicate a process id, negative values other than -1 indicate a process group id. if fildes does not refer to a socket, the results are unspecified.

F_SETOWN

If fildes refers to a socket, set the process group id specified to receive SIGURG signals when out-of-band data is available, using the value of arg taken as type int. Positive values indicate a process id, negative values other than -1 indicate a process group id. if fildes does not refer to a socket, the results are unspecified.

F_GETADV

Get the default advice that will be assumed by the system when the file is accessed. The return value of the function will be the value of the advice parameter, which will not be negative. Possible values are:

F_PLC_DEFAULT: Specifies that system default policies apply.
F_REPLICATE: Specifies that the file will be accessed in readonly fashion and replication of pages at each CPU-Group in a partitioned system is appropriate.
F_BALANCED: Specifies that the file will be accessed read/write, or readonly but such that replication at each CPU-Group in a partitioned system is not desired. It is expected that the file will be accessed from many CPU-Groups, so it is appropriate to allocate physical memory so as to spread it evenly across these CPU-Groups.
F_CPUGROUP: Specifies that the memory for the file should be preferentially allocated from just one CPU-Group.
F_FIRSTUSAGE: Specifies that the memory for the file should be preferentially allocated on the CPU-Group where it was first referenced.

F_SETADV

Set default advice to the system to take effect when the file is accessed. The third argument is an integer that passes the advice, encoded by the values given for F_GETADV, possibly modified by a bitwise or with F_MIGRATE. If F_BALANCED is set explicitly, the set of CPU-Groups used for balanced allocation is the entire set of online CPU-Groups. If F_CPUGROUP is set then the CPU-Groups to be used for allocation is the one where the caller is currently executing. If F_MIGRATE is set, the advice should apply to current allocations as well as to future ones.

The system advice given via F_SETADV may influence accesses made by other processes in the system. It remains current until the last close of the file or until it is changed by a further use of F_SETADV.

The persistence of the advice given via F_SETADV after the last close of the file is undefined. The effect on the current advice for a particular process of another process giving system advice via F_SETADV is undefined. Text files mapped by exec(2) follow the fcntl specified placement policy.

F_GETCPUGROUP

Get the CPU-Group that is to be used for allocation when F_GETCPUGROUP is set. The return value of the function will be the value of the CPU-Group identifier, which will not be negative. Should F_GETCPUGROUP not be in effect, the return value will be NOCGID.

F_SETCPUGROUP

Instruct the system that allocations for the file are to be taken from a particular CPU-Group. The third parameter contains the CPU-Group identifier. This call implicitly sets the advice to F_CPUGROUP.

F_GETGRAN

Get the granularity to be used for balanced placement. (This is akin to stripe size, but does not require a particular allocation pattern).

F_SETGRAN

Set the granularity to be used for balanced placement.

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_SETLK64

Set or clear a file segment lock according to the flock64 structure that arg points to (see fcntl(5)). F_SETLK64 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_SETLKW64

This cmd is the same as F_SETLK64 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

Get the first lock which blocks the lock description pointed to by the third argument arg, taken as a pointer to the type struct flock. The information retrieved overwrites the information passed to fcntl in the structure flock. If no lock is found that would prevent this lock from being created, the structure is left unchanged except for the lock type which is set to F_UNLCK.

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.

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

F_GETLK64

Get the first lock which blocks the lock description pointed to by the third argument arg, taken as a pointer to the type struct flock64 (see fcntl(5)). The information retrieved overwrites the information passed to fcntl in the structure flock64. If no lock is found that would prevent this lock from being created, the structure is left unchanged except for the lock type which is set to F_UNLCK.

If the lock request described by the flock64 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.

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

F_RSETLK