maildir-sync.c revision 0db4290d60bfa00774f628276d38654c56abd68c
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi/* Copyright (C) 2004 Timo Sirainen */
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Here's a description of how we handle Maildir synchronization and
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi it's problems:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi We want to be as efficient as we can. The most efficient way to
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi check if changes have occurred is to stat() the new/ and cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi directories and uidlist file - if their mtimes haven't changed,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi there's no changes and we don't need to do anything.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Problem 1: Multiple changes can happen within a single second -
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi nothing guarantees that once we synced it, someone else didn't just
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi then make a modification. Such modifications wouldn't get noticed
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi until a new modification occurred later.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Problem 2: Syncing cur/ directory is much more costly than syncing
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi new/. Moving mails from new/ to cur/ will always change mtime of
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi cur/ causing us to sync it as well.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Problem 3: We may not be able to move mail from new/ to cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi because we're out of quota, or simply because we're accessing a
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi read-only mailbox.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi MAILDIR_SYNC_SECS
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi -----------------
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Several checks below use MAILDIR_SYNC_SECS, which should be maximum
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi clock drift between all computers accessing the maildir (eg. via
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi NFS), rounded up to next second. Our default is 1 second, since
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi everyone should be using NTP.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Note that setting it to 0 works only if there's only one computer
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi accessing the maildir. It's practically impossible to make two
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi clocks _exactly_ synchronized.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi It might be possible to only use file server's clock by looking at
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi the atime field, but I don't know how well that would actually work.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi cur directory
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi -------------
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi We have dirty_cur_time variable which is set to cur/ directory's
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi mtime when it's >= time() - MAILDIR_SYNC_SECS and we _think_ we have
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi synchronized the directory.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi When dirty_cur_time is non-zero, we don't synchronize the cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi directory until
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi a) cur/'s mtime changes
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi b) opening a mail fails with ENOENT
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi c) time() > dirty_cur_time + MAILDIR_SYNC_SECS
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi This allows us to modify the maildir multiple times without having
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi to sync it at every change. The sync will eventually be done to
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi make sure we didn't miss any external changes.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi The dirty_cur_time is set when:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - we change message flags
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - we expunge messages
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - we move mail from new/ to cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - we sync cur/ directory and it's mtime is >= time() - MAILDIR_SYNC_SECS
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi It's unset when we do the final syncing, ie. when mtime is
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi older than time() - MAILDIR_SYNC_SECS.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi new directory
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi -------------
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi If new/'s mtime is >= time() - MAILDIR_SYNC_SECS, always synchronize
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi it. dirty_cur_time-like feature might save us a few syncs, but
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi that might break a client which saves a mail in one connection and
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi tries to fetch it in another one. new/ directory is almost always
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi empty, so syncing it should be very fast anyway. Actually this can
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi still happen if we sync only new/ dir while another client is also
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi moving mails from it to cur/ - it takes us a while to see them.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi That's pretty unlikely to happen however, and only way to fix it
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi would be to always synchronize cur/ after new/.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Normally we move all mails from new/ to cur/ whenever we sync it. If
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi it's not possible for some reason, we mark the mail with "probably
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi exists in new/ directory" flag.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi If rename() still fails because of ENOSPC or EDQUOT, we still save
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi the flag changes in index with dirty-flag on. When moving the mail
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi to cur/ directory, or when we notice it's already moved there, we
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi apply the flag changes to the filename, rename it and remove the
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi dirty flag. If there's dirty flags, this should be tried every time
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi after expunge or when closing the mailbox.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi This file contains UID <-> filename mappings. It's updated only when
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi new mail arrives, so it may contain filenames that have already been
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi deleted. Updating is done by getting uidlist.lock file, writing the
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi whole uidlist into it and rename()ing it over the old uidlist. This
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi means there's no need to lock the file for reading.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Whenever uidlist is rewritten, it's mtime must be larger than the old
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi one's. Use utime() before rename() if needed. Note that inode checking
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi wouldn't have been sufficient as inode numbers can be reused.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi This file is usually read the first time you need to know filename for
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi given UID. After that it's not re-read unless new mails come that we
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi don't know about.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi broken clients
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi --------------
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Originally the middle identifier in Maildir filename was specified
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi only as <process id>_<delivery counter>. That however created a
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi problem with randomized PIDs which made it possible that the same
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi PID was reused within one second.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi So if within one second a mail was delivered, MUA moved it to cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi and another mail was delivered by a new process using same PID as
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi the first one, we likely ended up overwriting the first mail when
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi the second mail was moved over it.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Nowadays everyone should be giving a bit more specific identifier,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi for example include microseconds in it which Dovecot does.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi There's a simple way to prevent this from happening in some cases:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Don't move the mail from new/ to cur/ if it's mtime is >= time() -
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi MAILDIR_SYNC_SECS. The second delivery's link() call then fails
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi because the file is already in new/, and it will then use a
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi different filename. There's a few problems with this however:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - it requires extra stat() call which is unneeded extra I/O
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - another MUA might still move the mail to cur/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi - if first file's flags are modified by either Dovecot or another
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi MUA, it's moved to cur/ (you _could_ just do the dirty-flagging
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi but that'd be ugly)
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Because this is useful only for very few people and it requires
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi extra I/O, I decided not to implement this. It should be however
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi quite easy to do since we need to be able to deal with files in new/
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi in any case.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi It's also possible to never accidentally overwrite a mail by using
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi link() + unlink() rather than rename(). This however isn't very
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi good idea as it introduces potential race conditions when multiple
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi clients are accessing the mailbox:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi Trying to move the same mail from new/ to cur/ at the same time:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi a) Client 1 uses slightly different filename than client 2,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi for example one sets read-flag on but the other doesn't.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi You have the same mail duplicated now.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi b) Client 3 sees the mail between Client 1's and 2's link() calls
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi and changes it's flag. You have the same mail duplicated now.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi And it gets worse when they're unlink()ing in cur/ directory:
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi c) Client 1 changes mails's flag and client 2 changes it back
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi between 1's link() and unlink(). The mail is now expunged.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi d) If you try to deal with the duplicates by unlink()ing another
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi one of them, you might end up unlinking both of them.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi So, what should we do then if we notice a duplicate? First of all,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi it might not be a duplicate at all, readdir() might have just
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi returned it twice because it was just renamed. What we should do is
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi create a completely new base name for it and rename() it to that.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi If the call fails with ENOENT, it only means that it wasn't a
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi duplicate after all.
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi/* When rename()ing many files from new/ to cur/, it's possible that next
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi readdir() skips some files. we don't of course wish to lose them, so we
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi go and rescan the new/ directory again from beginning until no files are
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi left. This value is just an optimization to avoid checking the directory
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi twice unneededly. usually only NFS is the problem case. 1 is the safest
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi bet here, but I guess 5 will do just fine too. */
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi struct maildir_uidlist_sync_ctx *uidlist_sync_ctx;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi struct maildir_index_sync_context *index_sync_ctx;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi struct maildir_keywords_sync_ctx *keywords_sync_ctx;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi array_t ARRAY_DEFINE(sync_recs, struct mail_index_sync_rec);
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomiint maildir_filename_get_flags(struct maildir_index_sync_context *ctx,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi const char *fname,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi const char *info;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi if (info == NULL || info[1] != '2' || info[2] != MAILDIR_FLAGS_SEP)
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi for (info += 3; *info != '\0' && *info != MAILDIR_FLAGS_SEP; info++) {
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi /* unknown keyword. */
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi /* unknown flag - ignore */
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomimaildir_filename_append_keywords(struct maildir_keywords_sync_ctx *ctx,
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi const unsigned int *indexes;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi unsigned int i, count;
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomi for (i = 0; i < count; i++) {
f6de86ea29e87fba001b6231d38a4c51e8a5c543Aki Tuomiconst char *maildir_filename_set_flags(struct maildir_index_sync_context *ctx,
int nextflag;
oldflags++;
oldflags++;
void *context)
const char *newpath;
unsigned int i, count;
for (i = 0; i < count; i++) {
i_unreached();
unsigned int i, count;
for (i = 0; i < count; i++) {
i_unreached();
if (expunged) {
} else if (flag_changed) {
for (i = count; i > 0; i--) {
&count);
if (count == 0) {
int ret;
if (ret <= 0)
return ret;
} while (ret > 0);
return ret;
static struct maildir_sync_context *
return ctx;
const char *old_fname)
int ret = 0;
t_push();
t_pop();
return ret;
const char *dir;
unsigned int moves = 0;
t_push();
if (ret == 0) {
if (new_dir)
if (ret < 0)
flags = 0;
if (move_new) {
moves++;
moves++;
} else if (new_dir) {
if (ret <= 0) {
if (ret < 0)
t_pop();
cur_mtime : 0;
struct maildir_index_sync_context *
return NULL;
return sync_ctx;
int partial)
const char *filename;
seq = 0;
unsigned int, MAILDIR_MAX_KEYWORDS);
unsigned int, MAILDIR_MAX_KEYWORDS);
seq++;
if ((uflags &
MAILDIR_UIDLIST_REC_FLAG_NONSYNCED) != 0) {
if ((uflags &
MAILDIR_UIDLIST_REC_FLAG_RACING) != 0) {
filename);
seq--;
flags);
goto __again;
if ((uflags &
MAILDIR_UIDLIST_REC_FLAG_NONSYNCED) != 0) {
seq--;
seq--;
flags);
if (!partial) {
if (uid_validity == 0) {
} else if (uid_validity == 0) {
if (ret < 0) {
else if (seq != 0) {
if (ret == 0) {
int sync_last_commit)
if (sync_last_commit) {
} else if (!forced) {
if (ret <= 0) {
return ret;
if (ret < 0)
if (cur_changed) {
if (ret < 0) {
if (ret == 0)
int ret;
int ret;
struct mailbox_sync_context *
int ret = 0;
ioloop_time) {
if (ret == 0) {
t_push();
t_pop();