Back to index

courier  0.68.2
mail.h
Go to the documentation of this file.
00001 
00002 #ifndef liblockmail_h
00003 #define liblockmail_h
00004 
00005 /*
00006 ** Copyright 2002 Double Precision, Inc.  See COPYING for
00007 ** distribution information.
00008 */
00009 
00010 #ifdef __cplusplus
00011 extern "C" {
00012 #endif
00013 
00014        /*
00015        ** Functions for mbox mail locks
00016        */
00017 
00018 struct ll_mail {
00019        char *file;          /* File being locked */
00020 
00021        /* c-client type lock */
00022 
00023        int cclientfd;
00024        char *cclientfile;
00025 
00026 
00027        /* dotlock */
00028 
00029        char *dotlock;
00030 };
00031 
00032 struct ll_mail *ll_mail_alloc(const char *filename);
00033 
00034 /*
00035 ** Create a c-client type lock.  NOTE: c-clients will ping you with SIGUSR2,
00036 ** which must be ignored for this implementation.
00037 ** Returns: 0 - ok, < 0 - error.
00038 **
00039 ** An error return from ll_mail_lock carries some additional context in
00040 ** errno:
00041 **
00042 ** errno == EAGAIN: potential race condition.  The current lock holder MIGHT
00043 ** have just terminated.  The caller should sleep for AT LEAST 5 seconds, then
00044 ** try again.
00045 **
00046 ** errno == EEXIST: another process on this server DEFINITELY has the lock.
00047 **
00048 ** Implementations might choose to wait and try again on EEXIST as well.
00049 */
00050 
00051 int ll_mail_lock(struct ll_mail *);
00052 
00053 /*
00054 ** Open the mail file, read/write (creating a dot-lock).
00055 ** Returns: >= 0 - file descriptor, < 0 - error (if EPERM, try ll_open_ro).
00056 **
00057 ** errno == EEXIST: another process appears to hold a dot-lock.
00058 **
00059 ** errno == EAGAIN: We just blew away a stale dotlock, should try again
00060 ** in at least five seconds.  Should NOT get two EAGAIN's in a row.
00061 */
00062 
00063 int ll_mail_open(struct ll_mail *);
00064 
00065 /*
00066 ** Open in read-only mode.
00067 */
00068 
00069 int ll_mail_open_ro(struct ll_mail *);
00070 
00071 /*
00072 ** Release all locks, deallocate structure.  NOTE: file descriptor from
00073 ** ll_mail_open(_ro)? is NOT closed, it's your responsibility to do that.
00074 */
00075 
00076 void ll_mail_free(struct ll_mail *);
00077 
00078 /*
00079 ** As long as we have the logic done already, here's a generic dot-locking
00080 ** function.
00081 **
00082 ** dotlock - the actual filename of a dotlock file.
00083 ** tmpfile - the filename of a temporary file to create first.
00084 ** timeout - optional timeout.
00085 **
00086 ** Return code: 0: dotlock is created.  Just unlink(dotlock) when you're done.
00087 **
00088 ** -1 error.  Check errno:
00089 **
00090 **    EEXIST - dotlock is locked
00091 **
00092 **    EAGAIN - dotlock is stale (dotlock created on this machine, and the
00093 **             process no longer exists, or dotlock created on another
00094 **             machine, and timeout argument was > 0, and the dotlock's
00095 **             timestamp was older than timeout seconds.
00096 **
00097 **    E????? - something's broken.
00098 **           
00099 */
00100 
00101 int ll_dotlock(const char *dotlock, const char *tmpfile,
00102               int timeout);
00103 
00104 #ifdef __cplusplus
00105 }
00106 #endif
00107 
00108 #endif