fcntl() -- System Call (libc)

Control open files
#include <fcntl.h>
int fcntl(fd, command, arg)
int fd, cmd, arg;

The COHERENT system call fcntl() manipulates an open file.

fd is the file descriptor; this  description must have been obtained from a
call to creat(), dup(), fcntl(), open(), or pipe().

command identifies  the task that  you want fcntl() to  perform.  The value
fcntl() returns  varies, depending on  what command you ask  it to perform.
arg is an argument specific to the given command.

fcntl() commands F_GETLK, F_SETLK, and F_SETLKW (described in detail below)
implement file-record locking.   File-record locks use the flock structure,
which is defined in header file <fcntl.h> as follows:

typedef struct flock {
     short     l_type;        /* F_RDLCK, F_WRLCK, or F_UNLCK*/
     short     l_whence;      /* SEEK_SET, SEEK_CUR, SEEK_END */
     long      l_start;       /* location */
     long      l_len;         /* 0 is through EOF */
     short     l_sysid;       /* system id of lock (for GETLK) */
     short     l_pid;         /* process id of owner (for GETLK) */
};

You can  lock a section of  a file for reading  (excluding subsequent write
locks) or for writing (excluding all subsequent locks).  The locked section
begins at  the specified  location l_start  and can extend  backwards (when
l_len is  negative) or forwards (when  it is positive).  If  l_len is zero,
the  lock extends  to the  end of  the file.   A lock  may extend  past the
current end  of file,  but may  not extend to  before the beginning  of the
file.

fcntl() Commands

fcntl() recognizes the following commands:

F_DUPFD Duplicate  file  descriptor   fd  onto  the  first  available  file
        descriptor greater  than or equal  to arg. fcntl()  returns the new
        file descriptor.

F_GETFD Get the current value  of the close-on-exec flag FD_CLOEXEC for the
        file.  If the low-order bit of the return value of fcntl() is zero,
        the  file descriptor  remains open  if the  process uses  exec() to
        execute another  process, If the low-order bit  of the return value
        is one, the file descriptor is closed upon exec().

F_GETFL Get the file flags for the  file specified by fd. With this option,
        fcntl() returns the file flags.

F_GETLK arg must  point to a struct  flock that describes a  section of the
        file  to lock.   If  the system  does  not have  any  locks on  the
        specified section, fcntl() sets the lock type of arg to F_UNLCK and
        leaves  the  other  members  unchanged.   Otherwise,  it  sets  the
        contents  of  arg  to  the  first  existing lock  that  blocks  the
        requested lock.

F_SETFD Set the close-on-exec flag of the  file to the value of the low bit
        of arg.

F_SETFL Set file  flags for  file descriptor fd  to the value  specified by
        arg. Here, fcntl() returns the new file flags.

F_SETLK Set or clear a file-record lock.  arg must point to a struct flock.
        Set member l_type to F_RDLCK to  request a read lock, to F_WRLCK to
        request a  write lock, or to F_UNLCK to  unlock a previously locked
        section.  If the requested lock cannot be set, fcntl() returns with
        an error value of -1 and sets errno to EACCES.

F_SETLKW
        is just like F_SETLK unless the requested lock is not available, in
        which case  F_SETLKW causes the current process  to sleep until the
        requested  lock  becomes  available.   If  sleeping would  cause  a
        deadlock, fcntl() returns -1 and sets errno to EDEADLK.

Upon failure, each  cmd returns -1 and sets errno  to an appropriate value.
Possible errno values include the following:

EAGAIN  Section already locked.

EBADF   Bad file desciptor.

EINVAL  Invalid command.

EMFILE  Too many files open.

ENOLCK  No more locks available.

EDEADLK Deadlock would result.

See Also

close(),
creat(),
dup(),
exec(),
fcntl.h,
file,
file descriptor,
libc,
lockf(),
open(),
pipe()
POSIX Standard §6.5.2

Notes

Use fcntl()  with the unbuffered I/O routines (open(),  write(), and so on)
rather  than  with  standard  I/O  library  routines  (fopen(),  fprintf(),
fwrite(), and so  on).  The buffering used by the  standard I/O library may
cause unexpected behavior with file locking.

© 2012 by Stephen A. Ness