summaryrefslogtreecommitdiff
path: root/include/mailutils/locker.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/mailutils/locker.h')
-rw-r--r--include/mailutils/locker.h200
1 files changed, 109 insertions, 91 deletions
diff --git a/include/mailutils/locker.h b/include/mailutils/locker.h
index 242bc2704..7d3b03d50 100644
--- a/include/mailutils/locker.h
+++ b/include/mailutils/locker.h
@@ -1,5 +1,5 @@
/* GNU Mailutils -- a suite of utilities for electronic mail
- Copyright (C) 1999-2019 Free Software Foundation, Inc.
+ Copyright (C) 1999-2024 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
@@ -25,105 +25,56 @@ 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"
+#define MU_LOCKER_DEFAULT_EXPIRE_TIME (10 * 60)
+#define MU_LOCKER_DEFAULT_RETRY_COUNT 10
+#define MU_LOCKER_DEFAULT_RETRY_SLEEP 1
+#define MU_LOCKER_DEFAULT_EXT_LOCKER "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
+enum
{
- mu_locker_assign,
- mu_locker_set_bit,
- mu_locker_clear_bit
+ MU_DL_EX_OK = 0, /* success */
+ MU_DL_EX_ERROR = 1, /* failed due to some other error */
+ MU_DL_EX_NEXIST = 2, /* unlock requested, but file is not locked */
+ MU_DL_EX_EXIST = 3, /* lock requested, but file is already locked */
+ MU_DL_EX_PERM = 4, /* insufficient permissions */
};
-
-/* mu_locker_create() flags */
/* Locker types */
+enum
+ {
+ MU_LOCKER_TYPE_DOTLOCK = 0, /* Dotlock-style locking. The default. */
+ MU_LOCKER_TYPE_EXTERNAL = 1, /* Use external program to lock the file. */
+ MU_LOCKER_TYPE_KERNEL = 2, /* Use kernel locking (flock,lockf,ioctl) */
+ MU_LOCKER_TYPE_NULL = 3, /* No locking at all. */
+ };
-#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_TYPE_DEFAULT MU_LOCKER_TYPE_DOTLOCK
-#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. */
+typedef struct
+{
+ int flags;
+ int type;
+ unsigned retry_count;
+ unsigned retry_sleep;
+ unsigned expire_time;
+ char *ext_locker;
+} mu_locker_hints_t;
+
+/* Locker hint flags */
+#define MU_LOCKER_FLAG_RETRY 0x0001 /* retry_count and retry_sleep are set */
+#define MU_LOCKER_FLAG_EXPIRE_TIME 0x0002 /* expire_time is set */
+#define MU_LOCKER_FLAG_CHECK_PID 0x0004 /* check if lock owner PID is active */
+#define MU_LOCKER_FLAG_EXT_LOCKER 0x0008 /* ext_locker is set */
+#define MU_LOCKER_FLAG_TYPE 0x0010 /* type is set */
+
+#define MU_LOCKER_FLAGS_ALL (\
+ MU_LOCKER_FLAG_TYPE | \
+ MU_LOCKER_FLAG_RETRY | \
+ MU_LOCKER_FLAG_EXPIRE_TIME | \
+ MU_LOCKER_FLAG_EXT_LOCKER | \
+ MU_LOCKER_FLAG_CHECK_PID )
-#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 int mu_locker_set_default_external_program (char const *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 */
@@ -132,12 +83,79 @@ enum mu_locker_mode
locking otherwise */
};
+#define MU_LOCKFILE_MODE 0644
+
+extern int mu_locker_create_ext (mu_locker_t *, const char *, mu_locker_hints_t *);
+extern int mu_locker_modify (mu_locker_t, mu_locker_hints_t *);
+extern void mu_locker_destroy (mu_locker_t *);
+
extern int mu_locker_lock_mode (mu_locker_t, enum mu_locker_mode);
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);
+extern int mu_locker_get_hints (mu_locker_t lck, mu_locker_hints_t *hints);
+
+extern mu_locker_hints_t mu_locker_defaults;
+
+/*
+ * Deprecated defines and interfaces.
+ */
+
+/* Legacy definitions for locker defaults */
+#define MU_LOCKER_EXPIRE_TIME MU_LOCKER_DEFAULT_EXPIRE_TIME
+#define MU_LOCKER_RETRIES MU_LOCKER_DEFAULT_RETRY_COUNT
+#define MU_LOCKER_RETRY_SLEEP MU_LOCKER_DEFAULT_RETRY_SLEEP
+#define MU_LOCKER_EXTERNAL_PROGRAM MU_LOCKER_DEFAULT_EXT_LOCKER
+
+/* Legacy definitions of locker types */
+#define MU_LOCKER_DOTLOCK (MU_LOCKER_TYPE_DOTLOCK << 8)
+#define MU_LOCKER_EXTERNAL (MU_LOCKER_TYPE_EXTERNAL << 8)
+#define MU_LOCKER_KERNEL (MU_LOCKER_TYPE_KERNEL << 8)
+#define MU_LOCKER_NULL (MU_LOCKER_TYPE_NULL << 8)
+
+/* Legacy definitions of locker flags (a.k.a. options). */
+#define MU_LOCKER_SIMPLE 0x0000
+#define MU_LOCKER_RETRY MU_LOCKER_FLAG_RETRY
+#define MU_LOCKER_TIME MU_LOCKER_FLAG_EXPIRE_TIME
+#define MU_LOCKER_PID MU_LOCKER_FLAG_CHECK_PID
+
+#define MU_LOCKER_DEFAULT (MU_LOCKER_DOTLOCK | MU_LOCKER_RETRY)
+
+/* The following was used to pack/unpack flags and locker type: */
+#define MU_LOCKER_TYPE_TO_FLAG(t) ((t) << 8)
+#define MU_LOCKER_FLAG_TO_TYPE(f) ((f) >> 8)
+#define MU_LOCKER_TYPE_MASK 0xff00
+#define MU_LOCKER_OPTION_MASK 0x00ff
+
+enum mu_locker_set_mode
+ {
+ mu_locker_assign,
+ mu_locker_set_bit,
+ mu_locker_clear_bit
+ };
+
+extern int mu_locker_create (mu_locker_t *, const char *, int) MU_DEPRECATED;
+
+extern int mu_locker_set_default_flags (int, enum mu_locker_set_mode) MU_DEPRECATED;
+extern void mu_locker_set_default_retry_timeout (time_t) MU_DEPRECATED;
+extern void mu_locker_set_default_retry_count (size_t) MU_DEPRECATED;
+extern void mu_locker_set_default_expire_timeout (time_t) MU_DEPRECATED;
+extern int mu_locker_set_default_external_program (char const *) MU_DEPRECATED;
+
+extern int mu_locker_set_flags (mu_locker_t, int) MU_DEPRECATED;
+extern int mu_locker_mod_flags (mu_locker_t, int, enum mu_locker_set_mode) MU_DEPRECATED;
+extern int mu_locker_set_expire_time (mu_locker_t, int) MU_DEPRECATED;
+extern int mu_locker_set_retries (mu_locker_t, int) MU_DEPRECATED;
+extern int mu_locker_set_retry_sleep (mu_locker_t, int) MU_DEPRECATED;
+extern int mu_locker_set_external (mu_locker_t, const char *) MU_DEPRECATED;
+
+extern int mu_locker_get_flags (mu_locker_t, int *) MU_DEPRECATED;
+extern int mu_locker_get_expire_time (mu_locker_t, int *) MU_DEPRECATED;
+extern int mu_locker_get_retries (mu_locker_t, int *) MU_DEPRECATED;
+extern int mu_locker_get_retry_sleep (mu_locker_t, int *) MU_DEPRECATED;
+
#ifdef __cplusplus
}
#endif

Return to:

Send suggestions and report system problems to the System administrator.