MAILLOCK(3MAIL) User Mailbox Library Functions MAILLOCK(3MAIL)
NAME
maillock, mailunlock, touchlock - functions to manage lockfile(s) for
user's mailbox
SYNOPSIS
cc [
flag ... ]
file ...
-lmail [
library ... ]
#include <maillock.h>
int maillock(
const char *user,
int retrycnt);
void mailunlock(
void);
void touchlock(
void);
DESCRIPTION
The
maillock() function attempts to create a lockfile for the user's
mailfile. If a lockfile already exists, and it has not been modified
in the last 5 minutes,
maillock() will remove the lockfile and set
its own lockfile.
It is crucial that programs locking mail files refresh their locks
at least every three minutes to maintain the lock. Refresh the
lockfile by calling the
touchlock() function with no arguments.
The algorithm used to determine the age of the lockfile takes into
account clock drift between machines using a network file system. A
zero is written into the lockfile so that the lock will be respected
by systems running the standard version of System V.
If the lockfile has been modified in the last 5 minutes the process
will sleep until the lock is available. The sleep algorithm is to
sleep for 5 seconds times the attempt number. That is, the first
sleep will be for 5 seconds, the next sleep will be for 10 seconds,
etc. until the number of attempts reaches
retrycnt.
When the lockfile is no longer needed, it should be removed by
calling
mailunlock().
The
user argument is the login name of the user for whose mailbox the
lockfile will be created.
maillock() assumes that user's mailfiles
are in the ``standard'' place as defined in <
maillock.h>.
RETURN VALUES
Upon successful completion, .
maillock() returns
0. Otherwise it
returns
-1.
FILES
/var/mail/* user mailbox files
/var/mail/*.lock user mailbox lockfiles
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+---------------+-----------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------+
|MT-Level | Unsafe |
+---------------+-----------------+
SEE ALSO
libmail(3LIB),
attributes(7)NOTES
The
mailunlock() function will only remove the lockfile created from
the most previous call to
maillock(). Calling
maillock() for
different users without intervening calls to
mailunlock() will cause
the initially created lockfile(s) to remain, potentially blocking
subsequent message delivery until the current process finally
terminates.
March 29, 1999 MAILLOCK(3MAIL)
