file-dotlock.h revision fdcb22a688c4676face8db865736b217d9c07d19
2690N/A#ifndef __FILE_DOTLOCK_H
2690N/A#define __FILE_DOTLOCK_H
2690N/A
2690N/A#include <unistd.h>
2690N/A#include <fcntl.h>
2690N/A
2690N/Astruct dotlock;
2690N/A
2690N/Astruct dotlock_settings {
2690N/A /* Dotlock files are created by first creating a temp file and then
2690N/A link()ing it to the dotlock. temp_prefix specifies the prefix to
2690N/A use for temp files. It may contain a full path. Default is
2690N/A ".temp.hostname.pid.". */
2690N/A const char *temp_prefix;
2690N/A /* Use this suffix for dotlock filenames. Default is ".lock". */
2690N/A const char *lock_suffix;
2690N/A
2690N/A /* Abort after this many seconds. */
2690N/A unsigned int timeout;
2690N/A /* Override the lock file when it and the file we're protecting is
2690N/A older than stale_timeout. */
2690N/A unsigned int stale_timeout;
2690N/A
3158N/A /* Callback is called once in a while. stale is set to TRUE if stale
2690N/A lock is detected and will be overridden in secs_left. If callback
2690N/A returns FALSE then, the lock will not be overridden. */
2690N/A bool (*callback)(unsigned int secs_left, bool stale, void *context);
2690N/A void *context;
2690N/A
2690N/A /* Rely on O_EXCL locking to work instead of using hardlinks.
2690N/A It's faster, but doesn't work with all NFS implementations. */
2690N/A unsigned int use_excl_lock:1;
2690N/A /* Use io_add_notify() to speed up finding out when an existing
2690N/A dotlock is deleted */
2690N/A unsigned int use_io_notify:1;
2690N/A};
2690N/A
2690N/Aenum dotlock_create_flags {
2690N/A /* If lock already exists, fail immediately */
2690N/A DOTLOCK_CREATE_FLAG_NONBLOCK = 0x01,
2690N/A /* Don't actually create the lock file, only make sure it doesn't
2690N/A exist. This is racy, so you shouldn't rely on it much. */
2690N/A DOTLOCK_CREATE_FLAG_CHECKONLY = 0x02
2690N/A};
2690N/A
2690N/Aenum dotlock_replace_flags {
2690N/A /* Check that lock file hasn't been overridden before renaming. */
2690N/A DOTLOCK_REPLACE_FLAG_VERIFY_OWNER = 0x01,
2690N/A /* Don't close the file descriptor. */
2690N/A DOTLOCK_REPLACE_FLAG_DONT_CLOSE_FD = 0x02
2690N/A};
2690N/A
2690N/A/* Create dotlock. Returns 1 if successful, 0 if timeout or -1 if error.
2690N/A When returning 0, errno is also set to EAGAIN. */
2690N/Aint file_dotlock_create(const struct dotlock_settings *set, const char *path,
2690N/A enum dotlock_create_flags flags,
2690N/A struct dotlock **dotlock_r);
2690N/A
2690N/A/* Delete the dotlock file. Returns 1 if successful, 0 if the file was already
2690N/A been deleted or reused by someone else, -1 if error. */
2690N/Aint file_dotlock_delete(struct dotlock **dotlock);
2690N/A
2690N/A/* Use dotlock as the new content for file. This provides read safety without
2690N/A locks, but it's not very good for large files. Returns fd for lock file.
2690N/A If locking timed out, returns -1 and errno = EAGAIN. */
2690N/Aint file_dotlock_open(const struct dotlock_settings *set, const char *path,
2690N/A enum dotlock_create_flags flags,
2690N/A struct dotlock **dotlock_r);
2690N/A/* Replaces the file dotlock protects with the dotlock file itself. */
2828N/Aint file_dotlock_replace(struct dotlock **dotlock,
2828N/A enum dotlock_replace_flags flags);
2690N/A/* Update dotlock's mtime. If you're keeping the dotlock for a long time,
2690N/A it's a good idea to update it once in a while so others won't override it.
2690N/A If the timestamp is less than a second old, it's not updated. */
2690N/Aint file_dotlock_touch(struct dotlock *dotlock);
2690N/A
2690N/A/* Returns the lock file path. */
2690N/Aconst char *file_dotlock_get_lock_path(struct dotlock *dotlock);
2690N/A
2690N/A#endif
2690N/A