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 



     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 net-
     work 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().






SunOS 5.11          Last change: 29 Mar 1999                    1






User Mailbox Library Functions                    maillock(3MAIL)



     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  .

RETURN VALUES
     Upon successful completion, .maillock() returns 0. Otherwise
     it returns -1.

FILES
     /var/mail/*         user mailbox files


     /var/mail/*.lock    user mailbox lockfiles


ATRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:



     
           ATRIBUTE TYPE               ATRIBUTE VALUE       
    
     MT-Level                     Unsafe                      
    


SEE ALSO
     libmail(3LIB),attributes(5)

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.
















SunOS 5.11          Last change: 29 Mar 1999                    2