Mercurial > dovecot > original-hg > dovecot-1.2

annotate src/lib/file-dotlock.h @ 8590:b9faf4db2a9f HEAD

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Updated copyright notices to include year 2009.
author Timo Sirainen <tss@iki.fi>
date Tue, 06 Jan 2009 09:25:38 -0500
parents b3303b65c3f2
children 2bbf175bb6d3
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6410
e4eb71ae8e96 Changed .h ifdef/defines to use <NAME>_H format.
Timo Sirainen <tss@iki.fi>
parents: 5938
diff changeset
1 #ifndef FILE_DOTLOCK_H
e4eb71ae8e96 Changed .h ifdef/defines to use <NAME>_H format.
Timo Sirainen <tss@iki.fi>
parents: 5938
diff changeset
2 #define FILE_DOTLOCK_H
1161
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
3
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
4 #include <unistd.h>
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
5 #include <fcntl.h>
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
6
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
7 struct dotlock;
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
8
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
9 struct dotlock_settings {
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
10 /* Dotlock files are created by first creating a temp file and then
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
11 link()ing it to the dotlock. temp_prefix specifies the prefix to
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
12 use for temp files. It may contain a full path. Default is
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
13 ".temp.hostname.pid.". */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
14 const char *temp_prefix;
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
15 /* Use this suffix for dotlock filenames. Default is ".lock". */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
16 const char *lock_suffix;
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
17
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
18 /* Abort after this many seconds. */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
19 unsigned int timeout;
3981
0d64f8888dcd Removed immediate_stale_timeout and changed the stale_timeout behavior to
Timo Sirainen <tss@iki.fi>
parents: 3863
diff changeset
20 /* Override the lock file when it and the file we're protecting is
0d64f8888dcd Removed immediate_stale_timeout and changed the stale_timeout behavior to
Timo Sirainen <tss@iki.fi>
parents: 3863
diff changeset
21 older than stale_timeout. */
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
22 unsigned int stale_timeout;
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
23
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
24 /* Callback is called once in a while. stale is set to TRUE if stale
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
25 lock is detected and will be overridden in secs_left. If callback
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
26 returns FALSE then, the lock will not be overridden. */
3863
55df57c028d4 Added "bool" type and changed all ints that were used as booleans to bool.
Timo Sirainen <tss@iki.fi>
parents: 3715
diff changeset
27 bool (*callback)(unsigned int secs_left, bool stale, void *context);
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
28 void *context;
3564
d3f246330d37 Support creating locks with O_EXCL.
Timo Sirainen <tss@iki.fi>
parents: 3106
diff changeset
29
d3f246330d37 Support creating locks with O_EXCL.
Timo Sirainen <tss@iki.fi>
parents: 3106
diff changeset
30 /* Rely on O_EXCL locking to work instead of using hardlinks.
d3f246330d37 Support creating locks with O_EXCL.
Timo Sirainen <tss@iki.fi>
parents: 3106
diff changeset
31 It's faster, but doesn't work with all NFS implementations. */
d3f246330d37 Support creating locks with O_EXCL.
Timo Sirainen <tss@iki.fi>
parents: 3106
diff changeset
32 unsigned int use_excl_lock:1;
6592
b6631550cf84 dotlocks: Flush NFS attribute cache only if nfs_flush setting is TRUE.
Timo Sirainen <tss@iki.fi>
parents: 6410
diff changeset
33 /* Flush NFS attribute cache before stating files. */
b6631550cf84 dotlocks: Flush NFS attribute cache only if nfs_flush setting is TRUE.
Timo Sirainen <tss@iki.fi>
parents: 6410
diff changeset
34 unsigned int nfs_flush:1;
5938
805f2527a982 If use_io_notify dotlock setting is enabled, use I/O notify loop for waiting
Timo Sirainen <tss@iki.fi>
parents: 3982
diff changeset
35 /* Use io_add_notify() to speed up finding out when an existing
805f2527a982 If use_io_notify dotlock setting is enabled, use I/O notify loop for waiting
Timo Sirainen <tss@iki.fi>
parents: 3982
diff changeset
36 dotlock is deleted */
805f2527a982 If use_io_notify dotlock setting is enabled, use I/O notify loop for waiting
Timo Sirainen <tss@iki.fi>
parents: 3982
diff changeset
37 unsigned int use_io_notify:1;
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
38 };
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
39
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
40 enum dotlock_create_flags {
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
41 /* If lock already exists, fail immediately */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
42 DOTLOCK_CREATE_FLAG_NONBLOCK = 0x01,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
43 /* Don't actually create the lock file, only make sure it doesn't
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
44 exist. This is racy, so you shouldn't rely on it much. */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
45 DOTLOCK_CREATE_FLAG_CHECKONLY = 0x02
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
46 };
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
47
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
48 enum dotlock_replace_flags {
3982
15c48c43cc75 Added file_dotlock_touch() for updating lock file's timestamp.
Timo Sirainen <tss@iki.fi>
parents: 3981
diff changeset
49 /* Check that lock file hasn't been overridden before renaming. */
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
50 DOTLOCK_REPLACE_FLAG_VERIFY_OWNER = 0x01,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
51 /* Don't close the file descriptor. */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
52 DOTLOCK_REPLACE_FLAG_DONT_CLOSE_FD = 0x02
1161
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
53 };
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
54
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
55 /* Create dotlock. Returns 1 if successful, 0 if timeout or -1 if error.
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
56 When returning 0, errno is also set to EAGAIN. */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
57 int file_dotlock_create(const struct dotlock_settings *set, const char *path,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
58 enum dotlock_create_flags flags,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
59 struct dotlock **dotlock_r);
1161
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
60
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
61 /* Delete the dotlock file. Returns 1 if successful, 0 if the file was already
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
62 been deleted or reused by someone else, -1 if error. */
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
63 int file_dotlock_delete(struct dotlock **dotlock);
1161
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
64
1597
9f503b7851ab Moved all dotlocking code to lib/. Also we now use temp file + link() rather
Timo Sirainen <tss@iki.fi>
parents: 1176
diff changeset
65 /* Use dotlock as the new content for file. This provides read safety without
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
66 locks, but it's not very good for large files. Returns fd for lock file.
1668
644268046d59 comment fix
Timo Sirainen <tss@iki.fi>
parents: 1597
diff changeset
67 If locking timed out, returns -1 and errno = EAGAIN. */
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
68 int file_dotlock_open(const struct dotlock_settings *set, const char *path,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
69 enum dotlock_create_flags flags,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
70 struct dotlock **dotlock_r);
8036
b3303b65c3f2 Added file_dotlock_open_mode().
Timo Sirainen <tss@iki.fi>
parents: 7134
diff changeset
71 /* Like file_dotlock_open(), but use the given file permissions. */
b3303b65c3f2 Added file_dotlock_open_mode().
Timo Sirainen <tss@iki.fi>
parents: 7134
diff changeset
72 int file_dotlock_open_mode(const struct dotlock_settings *set, const char *path,
b3303b65c3f2 Added file_dotlock_open_mode().
Timo Sirainen <tss@iki.fi>
parents: 7134
diff changeset
73 enum dotlock_create_flags flags,
b3303b65c3f2 Added file_dotlock_open_mode().
Timo Sirainen <tss@iki.fi>
parents: 7134
diff changeset
74 mode_t mode, uid_t uid, gid_t gid,
b3303b65c3f2 Added file_dotlock_open_mode().
Timo Sirainen <tss@iki.fi>
parents: 7134
diff changeset
75 struct dotlock **dotlock_r);
3106
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
76 /* Replaces the file dotlock protects with the dotlock file itself. */
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
77 int file_dotlock_replace(struct dotlock **dotlock,
9c4aa309dbac Changed dotlocking API.
Timo Sirainen <tss@iki.fi>
parents: 2246
diff changeset
78 enum dotlock_replace_flags flags);
3982
15c48c43cc75 Added file_dotlock_touch() for updating lock file's timestamp.
Timo Sirainen <tss@iki.fi>
parents: 3981
diff changeset
79 /* Update dotlock's mtime. If you're keeping the dotlock for a long time,
15c48c43cc75 Added file_dotlock_touch() for updating lock file's timestamp.
Timo Sirainen <tss@iki.fi>
parents: 3981
diff changeset
80 it's a good idea to update it once in a while so others won't override it.
15c48c43cc75 Added file_dotlock_touch() for updating lock file's timestamp.
Timo Sirainen <tss@iki.fi>
parents: 3981
diff changeset
81 If the timestamp is less than a second old, it's not updated. */
15c48c43cc75 Added file_dotlock_touch() for updating lock file's timestamp.
Timo Sirainen <tss@iki.fi>
parents: 3981
diff changeset
82 int file_dotlock_touch(struct dotlock *dotlock);
7134
9c2b65bfe604 Added file_dotlock_is_locked().
Timo Sirainen <tss@iki.fi>
parents: 6592
diff changeset
83 /* Returns TRUE if the lock is still ok, FALSE if it's been overridden. */
9c2b65bfe604 Added file_dotlock_is_locked().
Timo Sirainen <tss@iki.fi>
parents: 6592
diff changeset
84 bool file_dotlock_is_locked(struct dotlock *dotlock);
1597
9f503b7851ab Moved all dotlocking code to lib/. Also we now use temp file + link() rather
Timo Sirainen <tss@iki.fi>
parents: 1176
diff changeset
85
3715
9680bd9e6346 Added file_dotlock_get_lock_path()
Timo Sirainen <tss@iki.fi>
parents: 3564
diff changeset
86 /* Returns the lock file path. */
9680bd9e6346 Added file_dotlock_get_lock_path()
Timo Sirainen <tss@iki.fi>
parents: 3564
diff changeset
87 const char *file_dotlock_get_lock_path(struct dotlock *dotlock);
9680bd9e6346 Added file_dotlock_get_lock_path()
Timo Sirainen <tss@iki.fi>
parents: 3564
diff changeset
88
1161
fc5d2e44cc5e Locking code cleanups and small fixes
Timo Sirainen <tss@iki.fi>
parents:
diff changeset
89 #endif