NAME

       maillock, mailunlock, touchlock - manage mailbox lockfiles

SYNOPSIS

       #include <maillock.h>

       cc [ flag ... ] file ... -llockfile [ library ]

       int maillock( const char *user, int retrycnt );
       void mailunlock( void );
       void touchlock( void );

DESCRIPTION

       The  maillock function tries to create a lockfile for the users mailbox in an NFS-safe (or
       resistant) way. The algorithm is documented in lockfile_create(3).

       The mailbox is typically located in /var/mail.  The name  of  the  lockfile  then  becomes
       /var/mail/USERNAME.lock.   If  the environment variable $MAIL is set, and it ends with the
       same username as the username passed to maillock(), then that file is taken as the mailbox
       to lock instead.

       There  is  no  good  way to see if a lockfile is stale. Therefore if the lockfile is older
       then 5 minutes, it will be removed. That is why the touchlock function is provided:  while
       holding  the  lock,  it  needs  to  be  refreshed regulary (every minute or so) by calling
       touchlock ()  .

       Finally the mailunlock function removes the lockfile.

RETURN VALUES

       maillock returns one of the following status codes:

          #define L_SUCCESS   0    /* Lockfile created                     */
          #define L_NAMELEN   1    /* Recipient name too long (> 13 chars) */
          #define L_TMPLOCK   2    /* Error creating tmp lockfile          */
          #define L_TMPWRITE  3    /* Can't write pid int tmp lockfile     */
          #define L_MAXTRYS   4    /* Failed after max. number of attempts */
          #define L_ERROR     5    /* Unknown error; check errno           */
          #define L_RMSTALE   8    /* Failed to remove stale lockfile       */

NOTES

       These functions are not thread safe. If you need thread safe functions,  or  you  need  to
       lock   other   mailbox   (like)   files  that  are  not  in  the  standard  location,  use
       lockfile_create(3) instead.

       These functions call lockfile_create(3) to do the work. That function might  spawn  a  set
       group-id  executable  to  do the actual locking if the current process doesn't have enough
       priviliges.

       There are some issues with flushing the kernels attribute cache if you are using NFS - see
       the lockfile_create(3) manpage.

FILES

       /var/mail/user.lock,
       /usr/lib/liblockfile.so.1

AUTHOR

       Miquel van Smoorenburg

SEE ALSO

       lockfile_create(3), lockfile_touch (3), lockfile_remove(3)