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:
-
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.