maillock(3)

1MAILOCK(3)                 Linux Programmer's Manual                MAILOCK(3)
2
3
4

NAME

6       maillock, mailunlock, touchlock - manage mailbox lockfiles
7

SYNOPSIS

9       #include <maillock.h>
10
11       cc [ flag ... ] file ... -llockfile [ library ]
12
13       int maillock( const char *user, int retrycnt );
14       void mailunlock( void );
15       void touchlock( void );
16

DESCRIPTION

18       The  maillock function tries to create a lockfile for the users mailbox
19       in an NFS-safe (or resistant) way. The algorithm is documented in lock‐
20       file_create(3).
21
22       The  mailbox  is typically located in /var/mail.  The name of the lock‐
23       file then becomes /var/mail/USERNAME.lock.  If the environment variable
24       $MAIL is set, and it ends with the same username as the username passed
25       to maillock(), then that file is taken as the mailbox to lock instead.
26
27       There is no good way to see if a lockfile is stale.  Therefore  if  the
28       lockfile  is  older then 5 minutes, it will be removed. That is why the
29       touchlock function is provided: while holding the lock, it needs to  be
30       refreshed regulary (every minute or so) by calling touchlock ()  .
31
32       Finally the mailunlock function removes the lockfile.
33
34

RETURN VALUES

36       maillock returns one of the following status codes:
37
38          #define L_SUCCESS   0    /* Lockfile created                     */
39          #define L_NAMELEN   1    /* Recipient name too long (> 13 chars) */
40          #define L_TMPLOCK   2    /* Error creating tmp lockfile          */
41          #define L_TMPWRITE  3    /* Can't write pid int tmp lockfile     */
42          #define L_MAXTRYS   4    /* Failed after max. number of attempts */
43          #define L_ERROR     5    /* Unknown error; check errno           */
44          #define L_RMSTALE   8    /* Failed to remove stale lockfile       */
45
46

NOTES

48       These functions are not thread safe. If you need thread safe functions,
49       or you need to lock other mailbox (like) files  that  are  not  in  the
50       standard location, use lockfile_create(3) instead.
51
52       These  functions  call lockfile_create(3) to do the work. That function
53       might spawn a set group-id executable to do the actual locking  if  the
54       current process doesn't have enough priviliges.
55
56       There  are some issues with flushing the kernels attribute cache if you
57       are using NFS - see the lockfile_create(3) manpage.
58

FILES

60       /var/mail/user.lock,
61       /usr/lib/liblockfile.so.1
62
63

AUTHOR

65       Miquel van Smoorenburg
66
67