Copyright (C) 2000-2012 |
Manpages LOCKFILE_CREATESection: Linux Programmer's Manual (3 )Updated: 29 March 2001 Index Return to Main Contents NAMElockfile_create, lockfile_remove, lockfile_touch, lockfile_check - manage lockfilesSYNOPSIS#include <lockfile.h>cc [ flag ... ] file ... -llockfile [ library ]
int lockfile_create( const char *lockfile, int retrycnt, int flags );
DESCRIPTIONThe lockfile_create function creates a lockfile in an NFS safe way.If flags is set to L_PID then lockfile_create will not only check for an existing lockfile, but it will read the contents as well to see if it contains a process id in ASCII. If so, the lockfile is only valid if that process still exists. If the lockfile is on a shared filesystem, it might have been created by a process on a remote host. Thus the process-id checking is useless and the L_PID flag should not be set. In this case, 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 lockfile_touch function is provided: while holding the lock, it needs to be refreshed regulary (every minute or so) by calling lockfile_touch () . The lockfile_check function checks if a valid lockfile is already present without trying to create a new lockfile. Finally the lockfile_remove function removes the lockfile. RETURN VALUESlockfile_create 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 */ lockfile_check returns 0 if a valid lockfile is present. If no lockfile or no valid lockfile is present, -1 is returned. lockfile_touch and lockfile_remove return 0 on success. On failure -1 is returned and errno is set appropriately. ALGORITHMThe algorithm that is used to create a lockfile in an atomic way, even over NFS, is as follows:
REMOTE FILE SYSTEMS AND THE KERNEL ATTRIBUTE CACHEThese functions do not lock a file - they generate a lockfile. However in a lot of cases, such as Unix mailboxes, all concerned programs accessing the mailboxes agree on the fact that the presence of <filename>.lock means that <filename> is locked. If you are using lockfile_create to create a lock on a file that resides on a remote server, and you already have that file open, you need to flush the NFS attribute cache after locking. This is needed to prevent the following scenario:
Now the end of the file really isn't the end of the file - the kernel cached the attributes on open, and st_size is not the end of the file anymore. So after locking the file, you need to tell the kernel to flush the NFS file attribute cache. The only portable way to do this is the POSIX fcntl() file locking primitives - locking a file using fcntl() has the fortunate side-effect of invalidating the NFS file attribute cache of the kernel. lockfile_create() cannot do this for you for two reasons. One, it just creates a lockfile- it doesn't know which file you are actually trying to lock! Two, even if it could deduce the file you're locking from the filename, by just opening and closing it, it would invalidate any existing POSIX locks the program might already have on that file (yes, POSIX locking semantics are insane!). So basically what you need to do is something like this: fd = open("/var/mail/USER.lock"); .. program code .. lockfile_create("/var/mail/USER.lock", x, y); /* Invalidate NFS attribute cache using POSIX locks */ if (lockf(fd, F_TLOCK, 0) == 0) lockf(fd, F_ULOCK, 0); You have to be careful with this if you're putting this in an existing program that might already be using fcntl(), flock() or lockf() locking- you might invalidate existing locks.
There is also a non-portable way. A lot of NFS operations return the updated attributes - and the Linux kernel actually uses these to update the attribute cache. One of these operations is chmod(2). So stat()ing a file and then chmod()ing it to st.st_mode will not actually change the file, nor will it interfere with any locks on the file, but it will invalidate the attribute cache. The equivalent to use from a shell script would be chmod u=u /var/mail/USER PERMISSIONSIf you are on a system that has a mail spool directory that is only writable by a special group (usually "mail") you cannot create a lockfile directly in the mailspool directory without special permissions. Lockfile_create and lockfile_remove check if the lockfile ends in $USERNAME.lock, and if the directory the lockfile is writable by group "mail". If so, an external set group-id mail executable (dotlockfile(1) ) is spawned to do the actual locking / unlocking. FILES/usr/lib/liblockfile.so.1AUTHORMiquel van Smoorenburg <miquels@cistron.nl>SEE ALSOdotlockfile(1), maillock(3), touchlock (3), mailunlock(3)
Index
This document was created by man2html, using the manual pages. Time: 09:13:03 GMT, December 14, 2024 |