X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=lock.h;h=07d3ec34be536dd81b2e06274f6cc8bc2e1d982d;hb=98cfcef26048bba06975e68a1aad05a8bac0d65d;hp=0c9a5951639f0819c9bc9ceb951d4b4bcef5036f;hpb=54833b53da596625b194c40732f67aa9dd0ece54;p=~andy%2Ffetchmail

diff --git a/lock.h b/lock.h
index 0c9a5951..07d3ec34 100644
--- a/lock.h
+++ b/lock.h
@@ -1,12 +1,36 @@
+/** \file lock.h function declarations (API) for lock.c */
+
 #ifndef FM_LOCK_H
 #define FM_LOCK_H
 
-/* lock.c: concurrency locking */
-void lock_setup(struct runctl *);
-void lock_assert(void);
-void lock_or_die(void);
+/* from lock.c: concurrency locking */
+
+/** Set up the global \a lockfile variable (but do not lock yet). */
+void fm_lock_setup(struct runctl *);
+
+/** Assert that we already possess a lock. */
+void fm_lock_assert(void);
+
+/** Obtain a lock or exit the program with PS_EXCLUDE. This function is
+ * idempotent, that means it can be run even if we already have the
+ * lock. Note that fm_lock_setup() has to be run beforehand; this
+ * function does not check that condition. */
+void fm_lock_or_die(void);
+
+/** Release the lock (unlink the lockfile). */
 void fm_lock_release(void);
-int lock_state(void);
-void lock_dispose(void);
+
+/** Check the state of the lock file. If there is an error opening or
+ * reading the lockfile, exit with PS_EXCLUDE. If a stale lock file
+ * cannot be unlinked, complain and try to truncate it to 0 size. If
+ * truncation fails, complain and exit with PS_EXCLUDE.  \return
+ * -  0 if no lock is set
+ * - >0 if a fetchmail is running, but not in daemon mode
+ * - <0 if a fetchmail is running in daemon mode.
+ */
+int  fm_lock_state(void);
+
+/** Register an atexit() exit handler to dipose of the lock on process exit. */
+void fm_lock_dispose(void);
 
 #endif