mailunlock(3mail) [sunos man page]

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(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE 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.10							    29 Mar 1999 						   maillock(3MAIL)

Check Out this Related Man Page

MAILOCK(3)						     Linux Programmer's Manual							MAILOCK(3)

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	   */

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 <miquels@cistron.nl>

SEE ALSO

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

Linux Manpage							   28 March 2001							MAILOCK(3)

Linux and UNIX Man Pages

mailunlock(3mail) [sunos man page]

Check Out this Related Man Page