fcntl()

Provide control over an open file

Synopsis:

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

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

Arguments:

fildes: The descriptor for the file you want to control.
cmd: The command to execute; see below.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The fcntl() function provides control over the open file referenced by file descriptor fildes. To establish a lock with this function, open with write-only permission (O_WRONLY) or with read/write permission (O_RDWR).

The type of control is specified by the cmd argument, which may require a third data argument (arg). The cmd argument is defined in <fcntl.h>, and includes at least the following values:

F_ALLOCSP

Allocate storage space for the section of the file specified by the l_start, l_len, and l_whence fields of a struct flock structure pointed to by the additional argument to fcntl()

F_ALLOCSP64

Same as F_ALLOCSP, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

F_DUPFD

Allocate and return a new file descriptor that's the lowest numbered available (i.e., not already open) file descriptor greater than or equal to the third argument, arg, taken as an int. The new file descriptor refers to the same file as fildes, and shares any locks.

F_DUPFD_CLOEXEC

Similar to F_DUPFD, but also sets FD_CLOEXEC.

F_FREESP

Free storage space for the section of the file specified by the l_start, l_len, and l_whence fields of the struct flock structure pointed to by the additional argument to fcntl().

F_FREESP64

Same as F_FREESP, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

F_GETFD

Get the file descriptor flags (see F_SETFD, below) associated with the file descriptor fildes. File descriptor flags are associated with a single file descriptor, and don't affect other file descriptors referring to the same file.

F_GETFL

Get the file status flags and the file access modes associated with fildes. The flags and modes are defined in <fcntl.h>.

The file status flags (identified by the QNX Neutrino O_SETFLAG mask) include:

The file access modes are:

For more information, see open().

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 (defined in <fcntl.h>). For more information, see the flock structure section below. The information returned overwrites the information passed to fcntl() in the structure pointed to by arg.

If no lock is found that prevents this lock from being created, the structure is left unchanged, except for the lock type, which is set to F_UNLCK. If a lock is found, the l_pid member of the structure pointed to by arg is set to the process ID of the process holding the blocking lock and l_whence is set to SEEK_SET.

F_GETLK64

Same as F_GETLK, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

F_GETOWN

If the file descriptor refers to a socket, get the process or process group ID that's 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.

F_SETFD

Set the file descriptor flags associated with fildes to the third argument, arg, taken as type int. The only defined file descriptor flag is:

FD_CLOEXEC: If this flag is set, the file descriptor is closed across exec*(), posix_spawn*(), or spawn*() calls; else the file descriptor remains open.

F_SETFL

Set the file status flags, as shown for F_GETFL above, for the open file description associated with fildes from the corresponding bits in the third argument, arg, taken as type int. You can't use this function to change the file access mode. All bits set in arg, other than the file status bits, are ignored.

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, as defined in the header file <fcntl.h>, and documented below. This command is used to create the following locks (defined in <fcntl.h>):

F_RDLCK: Shared or read locks.
F_UNLCK: Remove either type of lock.
F_WRLCK: Exclusive or write locks.

If a lock can't be set, fcntl() returns immediately.

F_SETLK64

Same as F_SETLK, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

F_SETLKW

This command is the same as F_SETLK, except that when a lock is blocked by other locks, the process waits until the request can be satisfied. If a signal that's to be caught is received while fcntl() is waiting for a region, the call is interrupted without performing the lock operation, and fcntl() returns -1 with errno set to EINTR.

F_SETLKW64

Same as F_SETLKW, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

F_SETOWN

If the file descriptor refers to a socket, set the process or process group ID that you want to receive SIGURG signals when out-of-band data is available, to the value of the third argument, interpreted as an integer. Positive values indicate a process ID; negative values, other than -1, indicate a process group ID.

Note: In QNX Neutrino 6.6 or later, the large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see “Classification” in What's in a Function Description?

flock structure

The flock structure (also known as flock_t) contains at least the following members:

short l_type

One of F_RDLCK, F_WRLCK or F_UNLCK.

QNX Neutrino uses this structure for both flock() and the F_GETLK* and F_SETLK* commands for fcntl(). In QNX Neutrino 7.0 or later, and as a QNX Neutrino extension, if the structure is for a call to flock(), this member has F_FLOCK ORed into it. For more information, see the entry for iofunc_lock().

short l_whence

One of the following flags that specify where the relative offset, l_start, is measured from:

SEEK_CUR: Current seek position.
SEEK_END: End of file.
SEEK_SET: Start of file.

off_t l_start

Relative offset in bytes.

off_t l_len

Consecutive bytes to lock; if 0, then until EOF; if negative, the preceding bytes up to, but not including, the start byte.

pid_t l_pid

Process ID of the process holding the lock, returned when cmd is F_GETLK.

When a shared lock is set on a segment of a file, other processes can set shared locks on the same segment, or a portion of it. A shared lock prevents other processes from setting exclusive locks on any portion of the protected area. A request for a shared lock fails if the file was opened write-only.

An exclusive lock prevents any other process from setting a shared or an exclusive lock on a portion of the protected area. A request for an exclusive lock fails if the file was opened read-only.

Locks may start and extend beyond the current end of file, but may not start or extend before the beginning of the file; to attempt to do so is an error. A lock extends to “infinity” (the largest possible value for the file offset) if l_len is set to zero. If l_whence and l_start point to the beginning of the file, and l_len is zero, the entire file is locked.

The calling process may have only one type of lock set for each byte of a file. Before successfully returning from an F_SETLK or F_SETLKW request, the previous lock type (if any) for each byte in the specified lock region is replaced by the new lock type. All locks associated with a file for a given process are removed when a file descriptor for that file is closed by the process, or the process holding the file descriptor terminates. Locks aren't inherited by a child process using the fork() function. However, locks are inherited across exec*() or spawn*() calls.

Note:

A potential for deadlock occurs if a process controlling a locked region is put to sleep by attempting to lock another process's locked region. There's no detection for deadlocks involving file locks.
Locking is a protocol designed for updating a file shared among concurrently running applications. Locks are only advisory, that is, they don't prevent an errant or poorly-designed application from overwriting a locked region of a shared file. An application should use locks to indicate regions of a file that are to be updated by the application, and it should respect the locks of other applications.
The following functions ignore locks:
- ltrunc()
- open()
- read()
- sopen()
- write()

Returns:

-1 if an error occurred (errno is set). The successful return value(s) depend on the request type specified by arg, as shown below:

F_DUPFD: A new file descriptor.
F_GETFD: Value of the file descriptor flags (never a negative value).
F_GETFL: Value of the file status flags and access modes as shown above (never a negative value).
F_GETLK: Value other than -1.
F_GETOWN: Positive values indicate a process ID; negative values (other than -1) indicate a process group ID.
F_SETFD: Value other than -1.
(QNX Neutrino 7.0.4 or later) As a QNX Neutrino extension, the value returned on success is 0.
F_SETFL: Value other than -1.
F_SETLK: Value other than -1.
F_SETLKW: Value other than -1.
F_SETOWN: Value other than -1.

Errors:

EAGAIN

The cmd argument is F_SETLK, the type of lock (l_type) is a shared lock (F_RDLCK), and the segment of a file to be locked is already exclusive-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

One of the following occurred:

The fildes argument isn't a valid file descriptor.
The cmd argument is F_SETLK or F_SETLKW, the type of lock (l_type) is a shared lock (F_RDLCK), and fildes isn't a valid file descriptor open for reading.
The cmd argument is F_SETLK or F_SETLKW, the type of lock (l_type) is an exclusive lock (F_WRLCK), and fildes isn't a valid file descriptor open for writing.

EINTR

The cmd argument is F_SETLKW, and the function was interrupted by a signal.

EINVAL

One of the following occurred:

The cmd argument is invalid.
The cmd argument is F_DUPFD, and the third argument is negative, or greater than the configured number of maximum open file descriptors per process.
The cmd argument is F_GETLK, F_SETLK or F_SETLKW, and the data arg isn't valid, or fildes refers to a file that doesn't support locking.
The cmd argument is F_SETFL, and you specified one of the *SYNC flags, but IOFUNC_PC_SYNC_IO isn't set in the filesystem's mount configuration.

EMFILE

The cmd argument is F_DUPFD, and all file descriptors available to the process are open, or no file descriptors greater than or equal to arg are available.

ENOLCK

The cmd argument is F_SETLK or F_SETLKW, and satisfying the lock or unlock request causes the number of lock regions in the system to exceed the system-imposed limit.

ENOSYS

The filesystem doesn't support the operation.

EOVERFLOW

One of the values to be returned can't be represented correctly.

Examples:

/*
 * This program makes "stdout" synchronous
 * to guarantee the data is recoverable
 * (if it's redirected to a file).
 */
#include <unistd.h>
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>

int main( void )
{
    int flags, retval;

    flags = fcntl( STDOUT_FILENO, F_GETFL );

    flags |= O_DSYNC;

    retval = fcntl( STDOUT_FILENO, F_SETFL, flags );
    if( retval == -1 ) {
        printf( "error setting stdout flags\n" );
        return EXIT_FAILURE;
    }

    printf( "Hello, QNX Neutrino world.\n" );

    return EXIT_SUCCESS;
}

Classification:

POSIX 1003.1

Safety:
Cancellation point	Read the Caveats
Interrupt handler	No
Signal handler	Yes
Thread	Yes

Caveats:

A cancellation point occurs when a thread is executing fcntl() if the cmd argument is F_SETLKW; a cancellation point may occur in the case of F_DUPFD (when dupping across the network), F_GETFD, and F_SETFD.