2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
2007-04-12 22:42:49 +00:00
|
|
|
.\" Copyright 1993 Rickard E. Faith (faith@cs.unc.edu) and
|
2006-05-22 23:52:24 +00:00
|
|
|
.\" and Copyright 2002 Michael Kerrisk
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
2010-06-27 05:47:59 +00:00
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
.\"
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Modified Fri Jan 31 16:26:07 1997 by Eric S. Raymond <esr@thyrsus.com>
|
|
|
|
.\" Modified Fri Dec 11 17:57:27 1998 by Jamie Lokier <jamie@imbolc.ucc.ie>
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Modified 24 Apr 2002 by Michael Kerrisk <mtk.manpages@gmail.com>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\" Substantial rewrites and additions
|
2005-05-10 06:43:47 +00:00
|
|
|
.\" 2005-05-10 mtk, noted that lock conversions are not atomic.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2010-06-27 05:47:59 +00:00
|
|
|
.\" FIXME: Maybe document LOCK_MAND, LOCK_RW, LOCK_READ, LOCK_WRITE
|
|
|
|
.\" which only have effect for SAMBA.
|
2009-07-25 05:22:37 +00:00
|
|
|
.TH FLOCK 2 2009-07-25 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
flock \- apply or remove an advisory lock on an open file
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <sys/file.h>
|
|
|
|
.sp
|
2006-01-14 17:05:44 +00:00
|
|
|
.BI "int flock(int " fd ", int " operation );
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
Apply or remove an advisory lock on the open file specified by
|
|
|
|
.IR fd .
|
2008-07-10 20:53:08 +00:00
|
|
|
The argument
|
2004-11-03 13:51:07 +00:00
|
|
|
.I operation
|
|
|
|
is one of the following:
|
2007-12-23 22:02:16 +00:00
|
|
|
.RS 4
|
|
|
|
.TP 9
|
2004-11-03 13:51:07 +00:00
|
|
|
.B LOCK_SH
|
|
|
|
Place a shared lock.
|
|
|
|
More than one process may hold a shared lock for a given file
|
|
|
|
at a given time.
|
|
|
|
.TP
|
|
|
|
.B LOCK_EX
|
|
|
|
Place an exclusive lock.
|
|
|
|
Only one process may hold an exclusive lock for a given
|
|
|
|
file at a given time.
|
|
|
|
.TP
|
|
|
|
.B LOCK_UN
|
|
|
|
Remove an existing lock held by this process.
|
|
|
|
.RE
|
2007-12-23 22:02:16 +00:00
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
A call to
|
|
|
|
.BR flock ()
|
|
|
|
may block if an incompatible lock is held by another process.
|
accept.2, connect.2, eventfd.2, flock.2, open.2, posix_fadvise.2, read.2, recv.2, sched_setscheduler.2, select_tut.2, send.2, signalfd.2, splice.2, timerfd_create.2, write.2, flockfile.3, mkfifo.3, mq_notify.3, mq_open.3, pthread_tryjoin_np.3, scanf.3, random.4, ddp.7, epoll.7, fifo.7, ip.7, pipe.7, socket.7, spufs.7: Global fix: s/non-blocking/nonblocking/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:43:10 +00:00
|
|
|
To make a nonblocking request, include
|
2004-11-03 13:51:07 +00:00
|
|
|
.B LOCK_NB
|
2011-09-28 03:06:37 +00:00
|
|
|
(by ORing)
|
2004-11-03 13:51:07 +00:00
|
|
|
with any of the above operations.
|
|
|
|
|
|
|
|
A single file may not simultaneously have both shared and exclusive locks.
|
|
|
|
|
|
|
|
Locks created by
|
|
|
|
.BR flock ()
|
2005-06-21 14:43:56 +00:00
|
|
|
are associated with an open file table entry.
|
2004-11-03 13:51:07 +00:00
|
|
|
This means that duplicate file descriptors (created by, for example,
|
2007-04-12 22:42:49 +00:00
|
|
|
.BR fork (2)
|
2005-10-19 13:48:50 +00:00
|
|
|
or
|
|
|
|
.BR dup (2))
|
2004-11-03 13:51:07 +00:00
|
|
|
refer to the same lock, and this lock may be modified
|
|
|
|
or released using any of these descriptors.
|
|
|
|
Furthermore, the lock is released either by an explicit
|
|
|
|
.B LOCK_UN
|
|
|
|
operation on any of these duplicate descriptors, or when all
|
|
|
|
such descriptors have been closed.
|
|
|
|
|
2005-06-21 14:43:56 +00:00
|
|
|
If a process uses
|
|
|
|
.BR open (2)
|
|
|
|
(or similar) to obtain more than one descriptor for the same file,
|
|
|
|
these descriptors are treated independently by
|
|
|
|
.BR flock ().
|
|
|
|
An attempt to lock the file using one of these file descriptors
|
|
|
|
may be denied by a lock that the calling process has
|
|
|
|
already placed via another descriptor.
|
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
A process may only hold one type of lock (shared or exclusive)
|
|
|
|
on a file.
|
|
|
|
Subsequent
|
|
|
|
.BR flock ()
|
|
|
|
calls on an already locked file will convert an existing lock to the new
|
|
|
|
lock mode.
|
|
|
|
|
|
|
|
Locks created by
|
|
|
|
.BR flock ()
|
|
|
|
are preserved across an
|
|
|
|
.BR execve (2).
|
|
|
|
|
|
|
|
A shared or exclusive lock can be placed on a file regardless of the
|
|
|
|
mode in which the file was opened.
|
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
On success, zero is returned.
|
|
|
|
On error, \-1 is returned, and
|
2004-11-03 13:51:07 +00:00
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I fd
|
2007-10-04 16:02:37 +00:00
|
|
|
is not an open file descriptor.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINTR
|
|
|
|
While waiting to acquire a lock, the call was interrupted by
|
2008-07-04 15:50:36 +00:00
|
|
|
delivery of a signal caught by a handler; see
|
|
|
|
.BR signal (7).
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I operation
|
|
|
|
is invalid.
|
|
|
|
.TP
|
|
|
|
.B ENOLCK
|
|
|
|
The kernel ran out of memory for allocating lock records.
|
|
|
|
.TP
|
|
|
|
.B EWOULDBLOCK
|
|
|
|
The file is locked and the
|
|
|
|
.B LOCK_NB
|
|
|
|
flag was selected.
|
|
|
|
.SH "CONFORMING TO"
|
|
|
|
4.4BSD (the
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
call first appeared in 4.2BSD).
|
|
|
|
A version of
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock (),
|
2004-11-03 13:51:07 +00:00
|
|
|
possibly implemented in terms of
|
|
|
|
.BR fcntl (2),
|
intro.1, time.1, accept.2, bind.2, connect.2, execve.2, flock.2, getdents.2, getpriority.2, getuid.2, intro.2, ioctl.2, mincore.2, mknod.2, personality.2, ptrace.2, read.2, recv.2, select_tut.2, send.2, sendfile.2, shmctl.2, sigaction.2, signal.2, stat.2, times.2, truncate.2, umask.2, wait.2, MB_CUR_MAX.3, MB_LEN_MAX.3, argz_add.3, btowc.3, clearenv.3, clock.3, cmsg.3, end.3, endian.3, errno.3, exit.3, fgetwc.3, fgetws.3, fopen.3, fputwc.3, fputws.3, fseek.3, fwide.3, getfsent.3, getgrnam.3, gethostid.3, getipnodebyname.3, getmntent.3, getpwnam.3, getwchar.3, grantpt.3, iconv.3, iconv_close.3, iconv_open.3, insque.3, intro.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, malloc.3, mblen.3, mbrlen.3, mbrtowc.3, mbsinit.3, mbsnrtowcs.3, mbsrtowcs.3, mbstowcs.3, mbtowc.3, mkstemp.3, mktemp.3, nl_langinfo.3, openpty.3, posix_openpt.3, printf.3, ptsname.3, putwchar.3, qecvt.3, rcmd.3, readdir.3, rexec.3, rpc.3, setnetgrent.3, shm_open.3, sigpause.3, stdin.3, stpcpy.3, strftime.3, strptime.3, syslog.3, towctrans.3, towlower.3, towupper.3, ttyslot.3, ungetwc.3, unlocked_stdio.3, wcpcpy.3, wcpncpy.3, wcrtomb.3, wcscasecmp.3, wcscat.3, wcschr.3, wcscmp.3, wcscpy.3, wcscspn.3, wcsdup.3, wcslen.3, wcsncasecmp.3, wcsncat.3, wcsncmp.3, wcsncpy.3, wcsnlen.3, wcsnrtombs.3, wcspbrk.3, wcsrchr.3, wcsrtombs.3, wcsspn.3, wcsstr.3, wcstok.3, wcstombs.3, wcswidth.3, wctob.3, wctomb.3, wctrans.3, wctype.3, wcwidth.3, wmemchr.3, wmemcmp.3, wmemcpy.3, wmemmove.3, wmemset.3, wprintf.3, console_ioctl.4, pts.4, elf.5, filesystems.5, hosts.5, proc.5, ttytype.5, boot.7, capabilities.7, credentials.7, epoll.7, glob.7, koi8-r.7, path_resolution.7, pty.7, signal.7, suffixes.7, time.7, unicode.7, unix.7, uri.7, utf-8.7: global fix: s/Unix/UNIX/
The man pages were rather inconsistent in the use of "Unix"
versus "UNIX". Let's go with the trademark usage.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-10-12 04:45:38 +00:00
|
|
|
appears on most UNIX systems.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NOTES
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2007-04-12 22:42:49 +00:00
|
|
|
does not lock files over NFS.
|
|
|
|
Use
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR fcntl (2)
|
|
|
|
instead: that does work over NFS, given a sufficiently recent version of
|
|
|
|
Linux and a server which supports locking.
|
|
|
|
.PP
|
|
|
|
Since kernel 2.0,
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
is implemented as a system call in its own right rather
|
|
|
|
than being emulated in the GNU C library as a call to
|
|
|
|
.BR fcntl (2).
|
|
|
|
This yields true BSD semantics:
|
|
|
|
there is no interaction between the types of lock
|
|
|
|
placed by
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
|
|
|
.BR fcntl (2),
|
|
|
|
and
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
does not detect deadlock.
|
|
|
|
.PP
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
places advisory locks only; given suitable permissions on a file,
|
|
|
|
a process is free to ignore the use of
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and perform I/O on the file.
|
|
|
|
.PP
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR flock ()
|
2004-11-03 13:51:07 +00:00
|
|
|
and
|
|
|
|
.BR fcntl (2)
|
|
|
|
locks have different semantics with respect to forked processes and
|
|
|
|
.BR dup (2).
|
2005-06-21 14:43:56 +00:00
|
|
|
On systems that implement
|
|
|
|
.BR flock ()
|
|
|
|
using
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR fcntl (2),
|
2005-06-21 14:43:56 +00:00
|
|
|
the semantics of
|
|
|
|
.BR flock ()
|
|
|
|
will be different from those described in this manual page.
|
2005-05-10 06:43:47 +00:00
|
|
|
.PP
|
|
|
|
Converting a lock
|
|
|
|
(shared to exclusive, or vice versa) is not guaranteed to be atomic:
|
|
|
|
the existing lock is first removed, and then a new lock is established.
|
|
|
|
Between these two steps,
|
|
|
|
a pending lock request by another process may be granted,
|
2007-04-12 22:42:49 +00:00
|
|
|
with the result that the conversion either blocks, or fails if
|
2005-05-10 06:43:47 +00:00
|
|
|
.B LOCK_NB
|
|
|
|
was specified.
|
2007-06-08 09:56:56 +00:00
|
|
|
(This is the original BSD behavior,
|
2005-05-10 06:43:47 +00:00
|
|
|
and occurs on many other implementations.)
|
|
|
|
.\" Kernel 2.5.21 changed things a little: during lock conversion
|
|
|
|
.\" it is now the highest priority process that will get the lock -- mtk
|
2006-05-31 22:16:55 +00:00
|
|
|
.SH "SEE ALSO"
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR close (2),
|
|
|
|
.BR dup (2),
|
|
|
|
.BR execve (2),
|
|
|
|
.BR fcntl (2),
|
|
|
|
.BR fork (2),
|
|
|
|
.BR open (2),
|
|
|
|
.BR lockf (3)
|
|
|
|
|
2007-05-27 12:13:11 +00:00
|
|
|
See also
|
2009-07-25 05:32:12 +00:00
|
|
|
.I Documentation/filesystem/locks.txt
|
|
|
|
in the kernel source
|
|
|
|
.RI ( Documentation/locks.txt
|
|
|
|
in older kernels).
|