fcntl

File control.

Syntax

   #include <sys/types.h>

   #include <unistd.h>

   #include <fcntl.h>

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

Parameters

fildes

An open file descriptor.

cmd

The following values can be used for the file control command.

F_DUPFD: Duplicate file descriptor.
F_GETFD: Get file descriptor flags.
F_GETLK: Get record locking information.
F_SETFD: Set file descriptor flags.
F_GETFL: Get file status flags.
F_SETFL: Set file status flags.
F_SETLK: Set record locking information.
F_SETLKW: Set record locking information;wait if blocked.

FD_CLOEXEC: Close file descriptor upon execution of an exec-family function.

l_type Values for Record Locking With fcntl()

F_RDLCK: Shared or read lock.
F_UNLCK: Unlock.
F_WRLCK: Exclusive or write lock.

oflag Values for open()

O_CREAT: Create file if it does not exist.
O_EXCL: Exclusive use flag.
O_NOCITY: Do not assign a controlling terminal.
O_TRUNC: Truncate flag.

File Status Flags Used for open() and fcntl()

O_APPEND: Set append mode.
O_NONBLOCK: No delay.

File Access Modes Used for open() and fcntl()

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

Mask for Use With File Access Modes

O_ACCMODE: Mask for file access modes.

Return Values

>=0: Success. A nonnegative integer is returned representing the lowest numbered file descriptor not open by the calling process.
-1: An error occurred. The file is not opened, and errno is set to indicate the error condition.

Description

Upon successful completion, the value returned will depend on cmd. The various return values are shown in Table 6-9.

Otherwise, a value of -1 will be returned and errno will be set to indicate the error.

The available values for cmd are defined in the <fcntl.h> (see 6.5.1) which will include:

F_DUPFD

Return a new file descriptor that is the lowest numbered avaliable file descriptor greater than or equal to the third argument, arg, taken as an integer 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 cleared to keep the file open across calls to the exec family of functions.

F_GETFD

Get the file descriptor flags that are associated with the file descriptor fildes. File descriptor flags are associated with a single file descriptor and do not affect other file descriptors that refer to the same file.

F_GETLK

F_SETFD

Set the file descriptor flags that are associated with fildes to the third argument, arg taken as type int. If the FD_CLOEXEC flag is zero, the file will be closed upon successful execution of an exec function.

F_GETFL

Get the file status flags and the file access modes for the open file description associated with fildes. The file access modes can be extracted from the return value using the mask O_ACCMODE, which is defined in <fcntl.h>. File status flags and file access modes are associated with the open file description and do not affect other file descriptors that refer to the same file with different open file descriptions.

F_SETFL

Set the file status flags for the open file description associated with fildes from the corresponding bits in the third argument, arg, taken as type int. Bits corresponding to the file access modes and the oflag values that are set in arg are ignored. If any bits in arg other than those mentioned here are changed by the application, the result is unspecified.

The following commands are available for advisory record locking. Advisory record locking shall be supported for regular files, and may be supported for other files.

F_GETLK: Get the first lock that blocks the lock description pointed to by the third argument, arg, taken as a pointer to type struct flock (see below) The information retrived overwrites the information passed to fcntl() in the flock structure. If no lock is found that would prevent this lock from being created, the structure will be left unchanged by this function call except for the lock type, which will be set to F_UNLCK.
F_SETLK: Set or clear a file segment lock according to the lock description pointed to by the third argument, arg, taken as a pointer to type struct flock (see below). 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). F_RDLCK, F_WRLCK, and F_UNLCK are defined by the <fcntl.h> header. If shared or exclusive lock cannot be set, fcntl() will return immediately.
F_SETLKW: This command is the same as F_SETLK except that if a shared or exclusive lock is blocked by other locks, the process will wait until the request can be satisfied. If a signal that is to be caught is received while fcntl will be interrupted. Upon return from the signal handler of the process, fcntl() will return -1 with errno set to [EINTR], and the lock operation will not be done.

The flock structure, defined by the <fcntl.h> header, describes an advisory lock. It includes the members shown in Table 6-8.

When a shared lock has been set on a segment of a file, other processes will be able to 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 will fail if the file descriptor was not opened with read access.

An exclusive lock will prevent 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 will fail if the file descriptor was not opened with write access.

The value of l_whence is DEEK_SET, SEEK_CUR, or SEEK_END to indicate that the relative offset, L_START bytes, will be measured from the start of the file, current position, or end of the file, respectively, The value of l_en is the number of consecutive bytes to be locked. If l_len is negative, the result is undefined. The l_pid field is only used with F_GETLK to return the process ID of the process holeing a blocking lock. After a successful F_GETLK request, the value of l_whence will be SEEK_SET.

Table 4-1 flock Structure

Member Type	Member Name	Description
`short`	`l_type`	F_RDLCK,F_WRLCK,or F_UNLCK.
`short`	`l_whence`	F_RDLCK,F_WRLCK,or F_UNLCK.	Flag for starting offset.
`off_t`	`l_start`	Relative offset in bytes.
`off_t`	`l_len`	Size;if 0,then until EOF.
`pid_t`	`l_pid`	Process ID of the process holding the lock, returned with F_GETLK.

Locks may start and extend beyond the current end of a file, but, will not start or extend before the beginning of the file. A lock will be set to extend to the largest possible value of the file offset for that file is l_len is set to zero. If the flock struct has l_whence and l_start that point to the beginning of the file, and l_len of zero, the intire file will be locked.

There will be at most one type of lock set for each byte in the file. Before a successful return from an F_SETLK or an F_SETLKW 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 will be replaced by the new lock type. As specified above under the descriptions of shared locks and exclusive locks, and F_SETLK of an F_SETLKW request will (respectively) fail or block 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 will be 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 created useing the fork() function.

A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock the locked region of another process. If the system detects that sleeping until a locked region is unlocked would cause a deadlock, the fcntl() function will fail with an [EDEADLK]error.

Description

The function f cntl() provides for control over open files. The argument fildes is a file descriptor.

Implementation Considerations

The calling process must have the correct access permissions as defined by either an attached ACD or by the MPE/iX file security matrix. For example, a file opened O_RDONLY must have either ACD read access or MPE/iX read access. A file opened O_WRONLY or O_RDWR must have either ACD write access and append access or MPE/iX write access and append access.

Errors

If an error occurs, errno is set to one of the following values:

`EACCES`	CAUSE	One of the following: The calling process does not have search permission to a component of the pathname. The file does not exist and the calling process does not have write permission to the parent directory of the file to be created. The file exists and the permissions specified by `oflag` are denied. Both `O_TRUNC` and `O_RDONLY` were specified. Both `O_APPEND` and `O_RDONLY` were specified. An MPE/iX lockword is associated with the file.
	ACTION	One of the following: Make sure that the calling process has search permission to all directory components of the pathname. Make sure that the calling process has write permission to the parent directory of the file to be created. Specify valid and compatible flags in `oflag`. Remove the MPE/iX lockword.
`EBADF`	CAUSE	The `fildes` argument is not a valid file descriptor. The argument `cmd` is F_SETLK or F_SETLKW, the type of lock (l_type) is shared lock(F_RDLCK), and `fildes` is not a valid file descriptor open for reading. The argument `cmd` is F_SETLK or F_SETLKW, the type of lock (l_type) is an exclusive lock(F_WLRCK), and `fildes` is not a valid file descriptor open for writing.
	ACTION	None.
`EINTR`	CAUSE	The argument `cmd` is F_SETLKW, and the function was interrupted by a signal.
	ACTION	None.
`EINVAL`	CAUSE	More than one of the following three open flags were specified in `oflag`: `O_WRONLY`, `O_RDONLY`, and `O_RDWR`.
	ACTION	Specify only one of the open flags in `oflag`.
`EMFILE`	CAUSE	The argument `cmd` if F_DUPED and {OPEN_MAX} file descriptors are currently in use by this process, or no file descriptors greater than or equal to `arg` are available.
	ACTION	None.
`ENOLCK`	CAUSE	The argument `cmd` is F_SETLK or F_SETLKW, and satisfying the lock or unlock request would result in the number of locked regions in the system exceeding a system-imposed limit.
	ACTION	None.

For each of the following conditions, if the condition is detected, the fcntl() function will return -1 and set errno to the corresponding value:

`EDEADLK`	CAUSE	The argument `cmd` is F_SETLKW, and a deadlock condition was detected.
ACTION	None.
`EAGAIN`	CAUSE	The system lacked the resources to create another process.
ACTION	Attempt process creation at a later time, or decrease the number of processes associated with the application.
`EPERM`	CAUSE	One of the following: The calling process does not have the MPE/iX process handling (PH) capability. The calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource.
	ACTION	One of the following: Link the program file with the MPE/iX PH capability. Do not execute `execl()` when the calling process has outstanding switches to CM code, has set critical mode, has outstanding NOWAITIO, or is holding an operating system internal resource.

fcntl

Technical documentation

» Table of Contents

» Index

Syntax

Parameters

Return Values

Description

Description

Implementation Considerations

Errors

See Also