svn commit: r302401 - head/lib/libc/sys

[Jilles Tjoelker]

Author: jilles
Date: Thu Jul  7 21:44:59 2016
New Revision: 302401
URL: https://svnweb.freebsd.org/changeset/base/302401

Log:
  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)

Modified:
  head/lib/libc/sys/fcntl.2

Modified: head/lib/libc/sys/fcntl.2
==============================================================================
--- head/lib/libc/sys/fcntl.2	Thu Jul  7 21:03:50 2016	(r302400)
+++ head/lib/libc/sys/fcntl.2	Thu Jul  7 21:44:59 2016	(r302401)
@@ -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 whe
 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