Clarify and extend paragraphs on interoperation

of fcntl(2), flock(2), and lockf(3) advisory locks.
Add such a paragraph to the flock(2) manpage for the
sake of consistency.

Reviewed by:	Cyrille Lefevre and Kirk McKusick on -arch
MFC after:	2 weeks

3 files changed, 55 insertions, 6 deletions

diff --git a/lib/libc/gen/lockf.3 b/lib/libc/gen/lockf.3
index abb00ac3b8f7..63cf66967910 100644
--- a/lib/libc/gen/lockf.3
+++ b/lib/libc/gen/lockf.3
@@ -173,10 +173,22 @@ error.
 .Pp
 The
 .Fn lockf ,
-.Xr fcntl 2
+.Xr fcntl 2 ,
 and
 .Xr flock 2
-locks may be safely used concurrently.
+locks are compatible.
+Processes using different locking interfaces can cooperate
+over the same file safely.
+However, only one of such interfaces should be used within
+the same process.
+If a file is locked by a process through
+.Xr flock 2 ,
+any record within the file will be seen as locked
+from the viewpoint of another process using
+.Xr fcntl 2
+or
+.Fn lockf ,
+and vice versa.
 .Pp
 Blocking on a section is interrupted by any signal.
 .Sh RETURN VALUES
diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2
index c888890ebf6e..92b744035791 100644
--- a/lib/libc/sys/fcntl.2
+++ b/lib/libc/sys/fcntl.2
@@ -341,11 +341,26 @@ The
 system call is recommended for applications that want to ensure the integrity
 of their locks when using library routines or wish to pass locks
 to their children.
-Note that
-.Xr flock 2
+.Pp
+The
+.Fn fcntl ,
+.Xr flock 2 ,
 and
+.Xr lockf 3
+locks are compatible.
+Processes using different locking interfaces can cooperate
+over the same file safely.
+However, only one of such interfaces should be used within
+the same process.
+If a file is locked by a process through
+.Xr flock 2 ,
+any record within the file will be seen as locked
+from the viewpoint of another process using
 .Fn fcntl
-locks may be safely used concurrently but
+or
+.Xr lockf 3 ,
+and vice versa.
+Note that
 .Fn fcntl F_GETLK
 returns \-1 in
 .Fa l_pid
@@ -558,6 +573,7 @@ for the reasons as stated in
 .Xr getdtablesize 2 ,
 .Xr open 2 ,
 .Xr sigvec 2 ,
+.Xr lockf 3 ,
 .Xr tcgetpgrp 3 ,
 .Xr tcsetpgrp 3
 .Sh HISTORY
diff --git a/lib/libc/sys/flock.2 b/lib/libc/sys/flock.2
index 3cfc7cc423c2..1d095bdf3eba 100644
--- a/lib/libc/sys/flock.2
+++ b/lib/libc/sys/flock.2
@@ -112,6 +112,25 @@ references to a single lock.  If a process holding a lock on a file
 forks and the child explicitly unlocks the file, the parent will
 lose its lock.
 .Pp
+The
+.Fn flock ,
+.Xr fcntl 2 ,
+and
+.Xr lockf 3
+locks are compatible.
+Processes using different locking interfaces can cooperate
+over the same file safely.
+However, only one of such interfaces should be used within
+the same process.
+If a file is locked by a process through
+.Fn flock ,
+any record within the file will be seen as locked
+from the viewpoint of another process using
+.Xr fcntl 2
+or
+.Xr lockf 3 ,
+and vice versa.
+.Pp
 Processes blocked awaiting a lock may be awakened by signals.
 .Sh RETURN VALUES
 .Rv -std flock
@@ -141,8 +160,10 @@ refers to an object that does not support file locking.
 .Xr close 2 ,
 .Xr dup 2 ,
 .Xr execve 2 ,
+.Xr fcntl 2 ,
 .Xr fork 2 ,
-.Xr open 2
+.Xr open 2 ,
+.Xr lockf 3
 .Sh HISTORY
 The
 .Fn flock