RTEMS 4.9.3 On-Line Library

Input and Output Primitives Manager fcntl - Manipulates an open file descriptor

RTEMS POSIX API User's Guide

5.4.7: fcntl - Manipulates an open file descriptor

CALLING SEQUENCE:

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

int fcntl(
  int fildes,
  int cmd
);

STATUS CODES:

EACCESS: Search permission is denied for a direcotry in a file's path prefix.
EAGAIN: The O_NONBLOCK flag is set for a file descriptor and the process would be delayed in the I/O operation.
EBADF: Invalid file descriptor
EDEADLK: An fcntl with function F_SETLKW would cause a deadlock.
EINTR: The functioin was interrupted by a signal.
EINVAL: Invalid argument
EMFILE: Too many file descriptor or in use by the process.
ENOLCK: No locks available

DESCRIPTION:

fcntl() performs one of various miscellaneous operations on fd. The operation in question is determined by cmd:

F_DUPFD

Makes arg be a copy of fd, closing fd first if necessary.

The same functionality can be more easily achieved by using dup2().

The old and new descriptors may be used interchangeably. They share locks, file position pointers and flags; for example, if the file position is modified by using lseek() on one of the descriptors, the position is also changed for the other.

The two descriptors do not share the close-on-exec flag, however. The close-on-exec flag of the copy is off, meaning that it will be closed on exec.

On success, the new descriptor is returned.

F_GETFD

Read the close-on-exec flag. If the low-order bit is 0, the file will remain open across exec, otherwise it will be closed.

F_SETFD

Set the close-on-exec flag to the value specified by arg (only the least significant bit is used).

F_GETFL

Read the descriptor's flags (all flags (as set by open()) are returned).

F_SETFL

Set the descriptor's flags to the value specified by arg. Only O_APPEND and O_NONBLOCK may be set.

The flags are shared between copies (made with dup() etc.) of the same file descriptor.

The flags and their semantics are described in open().

F_GETLK, F_SETLK and F_SETLKW

Manage discretionary file locks. The third argument arg is a pointer to a struct flock (that may be overwritten by this call).

F_GETLK

Return the flock structure that prevents us from obtaining the lock, or set the l_type field of the lock to F_UNLCK if there is no obstruction.

F_SETLK

The lock is set (when l_type is F_RDLCK or F_WRLCK) or cleared (when it is F_UNLCK. If lock is held by someone else, this call returns -1 and sets errno to EACCES or EAGAIN.

F_SETLKW

Like F_SETLK, but instead of returning an error we wait for the lock to be released.

F_GETOWN

Get the process ID (or process group) of the owner of a socket.

Process groups are returned as negative values.

F_SETOWN

Set the process or process group that owns a socket.

For these commands, ownership means receiving SIGIO or SIGURG signals.

Process groups are specified using negative values.

NOTES:

The errors returned by dup2 are different from those returned by F_DUPFD.

RTEMS POSIX API User's Guide