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)