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_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 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 (see open() for more detailed information) are:

The file access modes are:

  • O_RDONLY — Open for reading only.
  • O_RDWR — Open for reading and writing.
  • O_WRONLY — Open for writing only.
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_SETFD
Set the file descriptor flags associated with fildes to the third argument, arg, taken as type int. See the above discussion for more details.

The only defined file descriptor flag is:

FD_CLOEXEC
When this flag is clear, the file remains open across spawn*() or exec*() calls; else the file is closed.
F_SETFL
Set the file status flags, as shown 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_GETLKW, except that the argument is a pointer to a struct flock64 structure, where the l_start and l_len fields are 64-bit values.

flock structure

The flock structure contains at least the following members:

short l_type
One of F_RDLCK, F_WRLCK or F_UNLCK.
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. If the system detects that sleeping until a locked region is unlocked would cause a deadlock, fcntl() fails with EDEADLK. However, the system can't always detect deadlocks in the network case, and care should be exercised in the design of your application for this possibility.
Note: 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:

Returns:

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

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_SETFD
Value other than -1.
F_SETFL
Value other than -1.
F_SETLK
Value other than -1.
F_SETLKW
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.
EDEADLK
The cmd argument is F_SETLKW, and a deadlock condition was detected.
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.
EMFILE
The cmd argument is F_DUPFD, and the process has no unused file descriptors, 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 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.