1 /* $Id: mail.h,v 1.3 2009/06/27 17:12:00 mrsam Exp $ */
7 ** Copyright 2002 Double Precision, Inc. See COPYING for
8 ** distribution information.
16 ** Functions for mbox mail locks
20 char *file
; /* File being locked */
22 /* c-client type lock */
33 struct ll_mail
*ll_mail_alloc(const char *filename
);
36 ** Create a c-client type lock. NOTE: c-clients will ping you with SIGUSR2,
37 ** which must be ignored for this implementation.
38 ** Returns: 0 - ok, < 0 - error.
40 ** An error return from ll_mail_lock carries some additional context in
43 ** errno == EAGAIN: potential race condition. The current lock holder MIGHT
44 ** have just terminated. The caller should sleep for AT LEAST 5 seconds, then
47 ** errno == EEXIST: another process on this server DEFINITELY has the lock.
49 ** Implementations might choose to wait and try again on EEXIST as well.
52 int ll_mail_lock(struct ll_mail
*);
55 ** Open the mail file, read/write (creating a dot-lock).
56 ** Returns: >= 0 - file descriptor, < 0 - error (if EPERM, try ll_open_ro).
58 ** errno == EEXIST: another process appears to hold a dot-lock.
60 ** errno == EAGAIN: We just blew away a stale dotlock, should try again
61 ** in at least five seconds. Should NOT get two EAGAIN's in a row.
64 int ll_mail_open(struct ll_mail
*);
67 ** Open in read-only mode.
70 int ll_mail_open_ro(struct ll_mail
*);
73 ** Release all locks, deallocate structure. NOTE: file descriptor from
74 ** ll_mail_open(_ro)? is NOT closed, it's your responsibility to do that.
77 void ll_mail_free(struct ll_mail
*);
80 ** As long as we have the logic done already, here's a generic dot-locking
83 ** dotlock - the actual filename of a dotlock file.
84 ** tmpfile - the filename of a temporary file to create first.
85 ** timeout - optional timeout.
87 ** Return code: 0: dotlock is created. Just unlink(dotlock) when you're done.
89 ** -1 error. Check errno:
91 ** EEXIST - dotlock is locked
93 ** EAGAIN - dotlock is stale (dotlock created on this machine, and the
94 ** process no longer exists, or dotlock created on another
95 ** machine, and timeout argument was > 0, and the dotlock's
96 ** timestamp was older than timeout seconds.
98 ** E????? - something's broken.
102 int ll_dotlock(const char *dotlock
, const char *tmpfile
,