DOC HOME SITE MAP MAN PAGES GNU INFO SEARCH
 

fcntl(S)


fcntl -- file control

Syntax

cc . . . -lc

#include  <fcntl.h>

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

Description

The fcntl system call provides for control over open files. The fildes argument is an open file descriptor obtained from a creat, open, dup, fcntl, or pipe system call. The data type and value of arg are specific to the type of command specified by cmd. The symbolic names for commands and file status flags are defined by the <fcntl.h> header file.

The commands available are:


F_DUPFD
Return a new file descriptor as follows:

F_GETFD
Get the close-on-exec flag associated with the file descriptor fildes. If the low-order bit is 0, the file remains open across exec; otherwise the file is closed upon execution of exec.

F_GETFL
Get file status flags (see open(S)).

F_SETFD
Set the close-on-exec flag associated with fildes to the low-order bit of arg (0 or 1 as above).

F_SETFL
Set file status flags to arg. Only certain flags can be set; see fcntl(M).

The following commands are used for file-locking and record-locking. Locks may be placed on an entire file or segments of a file.


F_GETLK
Get the first lock that blocks the lock description given by the variable of type struct flock pointed to by arg. The information retrieved overwrites the information passed to fcntl in the flock structure. If no lock is found that would prevent this lock from being created, then the structure is passed back unchanged except for the lock type which is set to F_UNLCK.

F_SETLK
Set or clear a file segment lock. According to the variable of type struct flock pointed to by arg (see fcntl(M)), the cmd F_SETLK is used to establish read (F_RDLCK) and write (F_WRLCK) locks. It also is used to remove either type of lock (F_UNLCK). If a read or write lock cannot be set, fcntl returns immediately with an error value of -1.

F_SETLKW
This cmd is the same as F_SETLK except that if a read or write lock is blocked by other locks, the process sleeps until the segment is free to be locked.

A read lock prevents any process from write locking the protected area. More than one read lock may exist for a given segment of a file at a given time. The file descriptor on which a read lock is being placed must have been opened with read access.

A write lock prevents any process from read-locking or write-locking the protected area. Only one write lock may exist for a given segment of a file at a given time. The file descriptor on which a write lock is being placed must have been opened with write access.

The structure flock defined in the <fcntl.h> header file describes a lock. It describes the type (l_type), starting offset (l_whence), relative offset (l_start), size (l_len), and process-ID (l_pid):

   short l_type;   /* F_RDLCK, F_WRLCK, F_UNLCK */
   short l_whence; /* flag for starting offset */
   long l_start;   /* relative offset in bytes */
   long l_len;     /* if 0 then until EOF */
   short l_pid;    /* returned with F_GETLK */
The value of l_whence is 0, 1, or 2 to indicate that the relative offset, l_start bytes, is measured from the start of the file, current position, or end of file, respectively. The value of l_len is the number of consecutive bytes to be locked. The process id is used only with the F_GETLK cmd to return the values for a blocking lock. Locks may start and extend beyond the current end of a file, but may not be negative relative to the beginning of the file. A lock may be set to always extend to the end of file by setting l_len to zero (0). If such a lock also has l_whence and l_start set to zero (0), the whole file is locked. Changing or unlocking a segment from the middle of a larger locked segment leaves two smaller segments for either end. Locking a segment that is already locked by the calling process causes the old lock type to be removed and the new lock type to take effect. All locks associated with a file for a given process are 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 in a fork system call.

When mandatory file and record locking is active on a file (see chmod(S)), read and write system calls issued on the file are affected by the record locks in effect.

The fcntl system call fails if one or more of the following is true:


[EACCES]
The cmd argument is F_SETLK, the type of lock (l_type) is a read (F_RDLCK) lock, and the segment of a file to be locked is already write locked by another process or the type is a write (F_WRLCK) lock and the segment of a file to be locked is already read or write locked by another process.

[EBADF]

  1. The fildes argument is not a valid open file descriptor.

  2. The cmd argument is F_SETLK or F_SETLKW, the type of lock (l_type) is a read-lock (F_RDLCK), and fildes is not a valid file-descriptor open for reading.

  3. The cmd argument is F_SETLK or F_SETLKW, the type of lock (l_type) is a write-lock (F_WRLCK), and fildes is not a valid file-descriptor open for writing.

[EDEADLK]
The cmd argument is F_SETLKW, the lock is blocked by some lock from another process, and putting the calling-process to sleep, waiting for that lock to become free, would cause a deadlock.

[EFAULT]
The cmd argument is F_SETLK, arg points outside the program address space.

[EINTR]
A signal was caught during the fcntl system call.

[EINVAL]

  1. The cmd argument is F_DUPFD. The arg argument is either negative, or greater than or equal to the configured value for the maximum number of open file descriptors allowed each user.

  2. The cmd argument is F_GETLK, F_SETLK, or SETLKW and arg or the data it points to is not valid.

[EMFILE]
The cmd argument is F_DUPFD and file-descriptors are currently open in the calling-process.

[ENOLCK]
The cmd argument is F_SETLK or F_SETLKW, the type of lock is a read or write lock, and there are no more record locks available (too many file segments locked) because the system maximum has been exceeded.

[ENOLINK]
fildes is on a remote machine and the link to that machine is no longer active.

Diagnostics

Upon successful completion, the value returned depends on cmd as follows:

F_DUPFD A new file descriptor.
F_GETFD Value of flag (only the low-order bit is defined).
F_GETFL Value of file flags.
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.

 F_DUPFD    A new file descriptor.
 F_GETFD    Value of flag (only the low-order bit is defined).
 F_GETFL    Value of file flags.
 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.

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

Warnings

Because in the future the variable errno will be set to EAGAIN rather than EACCES when a section of a file is already locked by another process, portable application programs should expect and test for either value.

See also

close(S), creat(S), dup(S), exec(S), fcntl(M), fork(S), open(S), pipe(S)

Standards conformance

fcntl is conformant with:

X/Open Portability Guide, Issue 3, 1989 ;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1) ;
and NIST FIPS 151-1 .


© 2003 Caldera International, Inc. All rights reserved.
SCO OpenServer Release 5.0.7 -- 11 February 2003