From 90b819c6d832046840018ff08b9bc5d0e3b69c37 Mon Sep 17 00:00:00 2001
From: Laurent Bercot <ska-skaware@skarnet.org>
Date: Sun, 29 Nov 2020 21:02:32 +0000
Subject:  Revamp lock primitives; prepare for 2.10.0.0 instead of 2.9.4.0

 flock() doesn't have a way to test for a lock without taking it.
 lockf() doesn't have shared locks.
 The only way to have both is fcntl(). So I rewrote all the
locking stuff around fcntl(), and used the opportunity to change
the interface.
 The point of changing the interface is to stop having to bother
with the old one, so to hell with compatibility, let's just do a
major bump.
---
 doc/index.html             |  2 +-
 doc/libstddjb/djbunix.html | 45 +++++++++++++--------------------------------
 doc/license.html           |  2 +-
 doc/upgrade.html           |  4 +++-
 4 files changed, 18 insertions(+), 35 deletions(-)

(limited to 'doc')

diff --git a/doc/index.html b/doc/index.html
index c7cb59c..66095a2 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -60,7 +60,7 @@ with a standard C development environment </li>
 <h3> Download </h3>
 
 <ul>
- <li> The current released version of skalibs is <a href="skalibs-2.9.4.0.tar.gz">2.9.4.0</a>. </li>
+ <li> The current released version of skalibs is <a href="skalibs-2.10.0.0.tar.gz">2.10.0.0</a>. </li>
  <li> Alternatively, you can checkout a copy of the
 <a href="//git.skarnet.org/cgi-bin/cgit.cgi/skalibs/">skalibs
 git repository</a>:
diff --git a/doc/libstddjb/djbunix.html b/doc/libstddjb/djbunix.html
index e70fe4f..54aaf50 100644
--- a/doc/libstddjb/djbunix.html
+++ b/doc/libstddjb/djbunix.html
@@ -202,45 +202,26 @@ with errno saved, used essentially to isolate application code from
 </p>
 
 <p>
-<code> int lock_ex (int fd) </code> <br />
-Gets an exclusive advisory lock on <em>fd</em>. <em>fd</em> must point to
-a regular file, open for writing. Blocks until the lock can be obtained.
-Returns 0 if it succeeds, or -1 (and sets errno) if it fails.
-</p>
-
-<p>
-<code> int lock_exnb (int fd) </code> <br />
-Gets an exclusive advisory lock on <em>fd</em>. <em>fd</em> must point to
-a regular file, open for writing.
-Returns 0 if it succeeds, or -1 (and sets errno) if it fails. If the lock
-is held and the function would block, it immediately returns with -1 EWOULDBLOCK.
-</p>
-
-<p>
-<code> int lock_sh (int fd) </code> <br />
-Gets a shared advisory lock on <em>fd</em>. <em>fd</em> must point to
-a regular file, open for reading. Blocks until the lock can be obtained.
-Returns 0 if it succeeds, or -1 (and sets errno) if it fails.
-</p>
-
-<p>
-<code> int lock_shnb (int fd) </code> <br />
-Gets a shared advisory lock on <em>fd</em>. <em>fd</em> must point to
-a regular file, open for reading.
-Returns 0 if it succeeds, or -1 (and sets errno) if it fails. If the lock
-is held and the function would block, it immediately returns with -1 EWOULDBLOCK.
+<code> int fd_lock (int fd, int w, int nb) </code> <br />
+Gets an advisory lock on <em>fd</em>: shared if <em>w</em> is
+zero, exclusive otherwise. <em>fd</em> must point to
+a regular file, open for writing or reading depending on whether
+you want an exclusive lock or not. If <em>nb</em> is zero, the
+function blocks until the lock can be obtained; otherwise it
+returns 0 immediately. On success, the function returns 1 ; it
+returns 0 if it cannot take the lock, or -1 (and sets errno) if
+an error occurs.
 </p>
 
 <p>
-<code> int lock_un (int fd) </code> <br />
+<code> void fd_unlock (int fd) </code> <br />
 Releases a previously held lock on <em>fd</em>.
-Returns 0 if it succeeds, or -1 (and sets errno) if it fails.
 </p>
 
 <p>
-<code> void lock_unx (int fd) </code> <br />
-Like <tt>lock_un</tt>, but without a return code and without
-modifying errno.
+<code> int fd_islocked (int fd) </code> <br />
+Returns 1 if a lock is currently held on fd, 0 otherwise.
+Returns -1 (and sets errno) if an error occurs.
 </p>
 
 <p>
diff --git a/doc/license.html b/doc/license.html
index 9aae77e..bfc1d5f 100644
--- a/doc/license.html
+++ b/doc/license.html
@@ -74,7 +74,7 @@ color, or different text font. </li>
 <p>
  <em>I am aware that the previous restrictions sound completely
 ridiculous while the official skalibs documentation is incomplete.
-As of 2.9.4.0, I'm not going to enforce those restrictions, but if you're
+As of 2.10.0.0, I'm not going to enforce those restrictions, but if you're
 going to provide documentation for skalibs, don't keep it to yourself,
 please send it to me instead. :-) </em>
 </p>
diff --git a/doc/upgrade.html b/doc/upgrade.html
index da2185c..8a87d7d 100644
--- a/doc/upgrade.html
+++ b/doc/upgrade.html
@@ -16,7 +16,7 @@
 <a href="//skarnet.org/">skarnet.org</a>
 </p>
 
-<h2> in 2.9.4.0 </h2>
+<h2> in 2.10.0.0 </h2>
 
 <ul>
  <li> New <tt>openc_*</tt> functions, which are O_CLOEXEC versions of the
@@ -25,6 +25,8 @@
 deleting a Unix domain socket. The <tt>ipc_bind_reuse()</tt> function now
 uses it, so it won't unconditionally clobber sockets in the filesystem anymore. </li>
  <li> Complete revamping of the pathexec functions, see <tt>exec.h</tt>. </li>
+ <li> Revamping of the locking functions, see
+<a href="libstddjb/djbunix.html>djbunix.h</a>. </li>
 </ul>
 
 <h2> in 2.9.3.0 </h2>
-- 
cgit v1.2.3