NAME

flock - apply or remove an advisory lock on an open file

SYNOPSIS

#include <sys/file.h> int flock(int fd, int operation)

DESCRIPTION

Apply or remove an advisory lock on an open file. The file is specified by fd. Valid operations are given below:

LOCK_SH

Shared lock. More than one process may hold a shared lock for a given file at a given time.

LOCK_EX

Exclusive lock. Only one process may hold an exclusive lock for a given file at a given time.

LOCK_UN

Unlock.

LOCK_NB

Don't block when locking. May be specified (by or'ing) along with one of the other operations.

A single file may not simultaneously have both shared and exclusive locks.

A file is locked (i.e., the inode), not the file descriptor. So, dup(2) and fork(2) do not create multiple instances of a lock.

RETURN VALUE

On success, zero is returned. On error, -1 is returned, and errno is set appropriately.

ERRORS

EWOULDBLOCK

The file is locked and the LOCK_NB flag was selected.

CONFORMING TO

4.4BSD (the flock(2) call first appeared in 4.2BSD).

NOTES

flock(2) does not lock files over NFS. Use fcntl(2) instead: that does work over NFS, given a sufficiently recent version of Linux and a server which supports locking.

flock(2) and fcntl(2) locks have different semantics with respect to forked processes and dup(2).

EXAMPLE

/*

• This program creates and locks /tmp/flock.example, waiting for the user
• before unlocking the file again.

*

• By running this program twice simultaniously, locking can be demonstrated.

*

• /

1. include <sys/file.h> /* for flock(2) */
2. include <sys/stat.h> /* for S_* constants */
3. include <string.h> /* for strerror(3) prototype */
4. include <stdio.h> /* for fprintf(3),printf(3),stderr protype */
5. include <errno.h> /* for errno prototype */
6. include <unistd.h> /* for close(2) prototypes */
7. define FILENAME "/tmp/flock.example"

int main(int argc,char **argv) {

int fd; char buf;

fd = open(FILENAME,O_RDWR|O_CREAT,S_IRUSR|S_IWUSR); if (fd==-1) {

fprintf(

stderr, "open(\"%s\",O_RDWR,S_IRUSR|S_IWUSR): %s (%i)\n", FILENAME, strerror(errno), errno);

return 1;

}

printf("Aquiring lock..."); fflush(stdout);

/* Aquire an exclusive lock */ if (flock(fd,LOCK_EX) == -1) {

fprintf(

stderr, "flock(fd,LOCK_EX): %s (%i)\n", strerror(errno), errno);

return 1;

} printf("Succeeded!\n");

printf("Press enter to release the lock.\n");

if (read(0,&buf,sizeof(buf)) == -1) {

printf("read(0,&buf,sizeof(buf)): %s (%i)\n",

strerror(errno), errno );

return 1;

}

printf("Releasing lock..."); fflush(stdout);

if (flock(fd,LOCK_UN)==-1) {

fprintf(

stderr, "flock(fd,LOCK_UN): %s (%i)\n", strerror(errno), errno);

return 1;

}

printf("Released!\n");

if (close(fd)==-1) {

fprintf(

stderr, "close(fd): %s (%i)\n", strerror(errno), errno);

return 1;

}

return 0;

}

SEE ALSO

open(2), close(2), dup(2), execve(2), fcntl(2), fork(2), lockf(3)

There are also locks.txt and mandatory.txt in /usr/src/linux/Documentation.