fcntl(2): Document interrupt/restart for file locks.

Since r302216, thread suspension causes advisory file locks to restart
(instead of continuing to wait) and for a long time SA_RESTART has
affected advisory file locks. These are both not compliant to POSIX.1.

To clarify that restarting means something, add a paragraph about fair
queuing. Note that the network lock manager does not implement fair
queuing.

Reviewed by:	kib (previous version)
Approved by:	re (gjb)

1 files changed, 22 insertions, 1 deletions

diff --git a/lib/libc/sys/fcntl.2 b/lib/libc/sys/fcntl.2
index 8e0ca73..cb91fba 100644
--- a/lib/libc/sys/fcntl.2
+++ b/lib/libc/sys/fcntl.2
@@ -28,7 +28,7 @@
 .\"     @(#)fcntl.2	8.2 (Berkeley) 1/12/94
 .\" $FreeBSD$
 .\"
-.Dd February 8, 2013
+.Dd July 7, 2016
 .Dt FCNTL 2
 .Os
 .Sh NAME
@@ -363,6 +363,13 @@ request fails or blocks respectively when another process has existing
 locks on bytes in the specified region and the type of any of those
 locks conflicts with the type specified in the request.
 .Pp
+The queuing for
+.Dv F_SETLKW
+requests on local files is fair;
+that is, while the thread is blocked,
+subsequent requests conflicting with its requests will not be granted,
+even if these requests do not conflict with existing locks.
+.Pp
 This interface follows the completely stupid semantics of System V and
 .St -p1003.1-88
 that require that all locks associated with a file for a given process are
@@ -646,6 +653,20 @@ The
 .Dv F_DUP2FD
 constant is non portable.
 It is provided for compatibility with AIX and Solaris.
+.Pp
+Per
+.St -susv4 ,
+a call with
+.Dv F_SETLKW
+should fail with
+.Bq Er EINTR
+after any caught signal
+and should continue waiting during thread suspension such as a stop signal.
+However, in this implementation a call with
+.Dv F_SETLKW
+is restarted after catching a signal with a
+.Dv SA_RESTART
+handler or a thread suspension such as a stop signal.
 .Sh HISTORY
 The
 .Fn fcntl