locker.h
5.53 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
/* GNU Mailutils -- a suite of utilities for electronic mail
Copyright (C) 1999-2001, 2005, 2007-2008, 2010-2012 Free Software
Foundation, Inc.
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 3 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General
Public License along with this library. If not, see
<http://www.gnu.org/licenses/>. */
#ifndef _MAILUTILS_LOCKER_H
#define _MAILUTILS_LOCKER_H
#include <mailutils/types.h>
#ifdef __cplusplus
extern "C" {
#endif
/* lock expiry time */
#define MU_LOCKER_EXPIRE_TIME (10 * 60)
#define MU_LOCKER_RETRIES (10)
#define MU_LOCKER_RETRY_SLEEP (1)
#define MU_LOCKER_EXTERNAL_PROGRAM "dotlock"
/* return codes for the external locker */
#define MU_DL_EX_PERM 4 /* insufficient permissions */
#define MU_DL_EX_EXIST 3 /* lock requested, but file is already locked */
#define MU_DL_EX_NEXIST 2 /* unlock requested, but file is not locked */
#define MU_DL_EX_ERROR 1 /* failed due to some other error */
#define MU_DL_EX_OK 0 /* success */
enum mu_locker_set_mode
{
mu_locker_assign,
mu_locker_set_bit,
mu_locker_clear_bit
};
/* mu_locker_create() flags */
/* Locker types */
#define MU_LOCKER_TYPE_DOTLOCK 0
#define MU_LOCKER_TYPE_EXTERNAL 1
/* Use an external program to lock the file. This is necessary
for programs having permission to access a file, but do not
have write permission on the directory that contains that file. */
#define MU_LOCKER_TYPE_KERNEL 2
/* Use kernel locking (flock, lockf or ioctl) */
#define MU_LOCKER_TYPE_NULL 3
/* Special locker type: means no lock. This is to be used with
temporary mailboxes stored in memory. */
#define MU_LOCKER_TYPE_TO_FLAG(t) ((t) << 8)
#define MU_LOCKER_FLAG_TO_TYPE(f) ((f) >> 8)
#define MU_LOCKER_IS_TYPE(f,t) (MU_LOCKER_FLAG_TO_TYPE(f) == (t))
#define MU_LOCKER_SET_TYPE(f,t) ((f) = MU_LOCKER_TYPE_TO_FLAG(t) | MU_LOCKER_OPTIONS(f))
#define MU_LOCKER_TYPE_MASK 0xff00
#define MU_LOCKER_OPTION_MASK 0x00ff
#define MU_LOCKER_OPTIONS(f) ((f) & MU_LOCKER_OPTION_MASK)
#define MU_LOCKER_NULL MU_LOCKER_TYPE_TO_FLAG(MU_LOCKER_TYPE_NULL)
#define MU_LOCKER_DOTLOCK MU_LOCKER_TYPE_TO_FLAG(MU_LOCKER_TYPE_DOTLOCK)
#define MU_LOCKER_EXTERNAL MU_LOCKER_TYPE_TO_FLAG(MU_LOCKER_TYPE_EXTERNAL)
#define MU_LOCKER_KERNEL MU_LOCKER_TYPE_TO_FLAG(MU_LOCKER_TYPE_KERNEL)
/* Options */
#define MU_LOCKER_SIMPLE 0x0000
/* Just try and dotlock the file, not the default because its usually
better to retry. */
#define MU_LOCKER_RETRY 0x0001
/* This requests that we loop retries times, sleeping retry_sleep
seconds in between trying to obtain the lock before failing with
MU_LOCK_CONFLICT. */
#define MU_LOCKER_TIME 0x0002
/* This mode checks the last update time of the lock, then removes
it if older than MU_LOCKER_EXPIRE_TIME. If a client uses this,
then the servers better periodically update the lock on the
file... do they? */
#define MU_LOCKER_PID 0x0004
/* PID locking is only useful for programs that aren't using
an external dotlocker, non-setgid programs will use a dotlocker,
which locks and exits imediately. This is a protection against
a server crashing, it's not generally useful. */
#define MU_LOCKER_DEFAULT (MU_LOCKER_DOTLOCK | MU_LOCKER_RETRY)
/* Use these flags for as the default locker flags (the default defaults
* to MU_LOCKER_DEFAULT). A flags of 0 resets the flags back to the
* the default.
*/
extern int mu_locker_set_default_flags (int flags, enum mu_locker_set_mode mode);
extern void mu_locker_set_default_retry_timeout (time_t to);
extern void mu_locker_set_default_retry_count (size_t n);
extern void mu_locker_set_default_expire_timeout (time_t t);
extern void mu_locker_set_default_external_program (char *path);
/* A flags of 0 means that the default will be used. */
extern int mu_locker_create (mu_locker_t *, const char *filename, int flags);
extern void mu_locker_destroy (mu_locker_t *);
/* Time is measured in seconds. */
extern int mu_locker_set_flags (mu_locker_t, int);
extern int mu_locker_mod_flags (mu_locker_t locker, int flags,
enum mu_locker_set_mode mode);
extern int mu_locker_set_expire_time (mu_locker_t, int);
extern int mu_locker_set_retries (mu_locker_t, int);
extern int mu_locker_set_retry_sleep (mu_locker_t, int);
extern int mu_locker_set_external (mu_locker_t, const char* program);
extern int mu_locker_get_flags (mu_locker_t, int*);
extern int mu_locker_get_expire_time (mu_locker_t, int*);
extern int mu_locker_get_retries (mu_locker_t, int*);
extern int mu_locker_get_retry_sleep (mu_locker_t, int*);
extern int mu_locker_get_external (mu_locker_t, char**);
enum mu_locker_mode
{
mu_lck_shr, /* Shared (advisory) lock */
mu_lck_exc, /* Exclusive lock */
mu_lck_opt /* Optional lock = shared, if the locker supports it, no
locking otherwise */
};
extern int mu_locker_lock (mu_locker_t);
extern int mu_locker_touchlock (mu_locker_t);
extern int mu_locker_unlock (mu_locker_t);
extern int mu_locker_remove_lock (mu_locker_t);
#ifdef __cplusplus
}
#endif
#endif