Maildir contents

A“maildir” is a directory that's created bymaildirmake(1).Naturally, maildirs should not have any group or world permissions,unless you want other people to read your mail.A maildir contains three subdirectories:tmp,new, andcur.These three subdirectories comprise the primary folder, where new mailis delivered by the system.

Folders areadditional subdirectories in the maildirwhose names begin with a period: such as.Drafts or.Sent.Each folder itself contains thesame three subdirectories,tmp,new,andcur,and an additional zero-length file namedmaildirfolder, whose purpose is to inform any maildelivery agent that it's really delivering to a folder, and thatthe mail delivery agent should look in the parent directory forany maildir-related information.

Folders are not physically nested.A folder subdirectory,such as.Sentdoes not itself contain any subfolders.The main maildir contains a single, flat list of subfolders.These folders are logically nested,and periods serve to separate folder hierarchies.For example,.Sent.2002 is considered to be a subfoldercalled“2002” which is a subfolder of“Sent”.

Messages

E-mail messages are stored in separate, individual files,one E-mail message per file.Thetmp subdirectory temporarilystores E-mail messages that are in the process of being deliveredto this maildir.tmp may alsostore other kinds of temporaryfiles, as long as they are created in the same way that message files arecreated intmp.Thenew subdirectory stores messagesthat have been delivered to this maildir, but have not yet been seen by anymail application.Thecur subdirectory stores messages that havealready been seen by mail applications.

Adding new mail to maildirs

The following process delivers a new message to the maildir:

A new unique filename is created using one of two possible forms:“time.MusecPpid.host”, or“time.MusecPpid_unique.host”.“time” and“usec”is the current systemtime, obtained fromgettimeofday(2).“pid” is the process number of the process that isdelivering this message to the maildir.“host” is the name of the machinewhere the mail is being delivered. In the event that the same processcreates multiple messages, a suffix unique to each messageis appended to the process id;preferrably an underscore, followed by an increasing counter. This applieswhether messages created by a process are all addedto the same, or different,maildirs.This protocol allows multiple processes running on multiple machineson the same network to simultaneously create new messages without stomping oneach other.

The filename created in the previous step is checked forexistence byexecuting thestat(2)system call.Ifstat(2)results in ANYTHING OTHERthan the system errorENOENT,the process must sleep for twoseconds, then go back and create another unique filename.This is an extra stepto insure that each new message has a completely unique filename.

Other applications that wish to usetmpfor temporary storageshould observe the same protocol (but see READING MAIL FROM MAILDIRS below,because old files intmp will be eventuallydeleted).

If thestat(2)system call returnedENOENT, the processmay proceed to create the file in thetmpsubdirectory, and savethe entire message in the new file. The message saved MUST NOT have the“From_” header that is used to mboxes.The message also MUST NOT have any“From_” linesin the contents of the message prefixed by the“>” character.

When saving the message,the number ofbytes returned by thewrite(2)system call must be checked, in orderto make sure that the complete message has been written out.

After the message is saved,the file descriptor isfstat(2)-ed.The file's device number, inode number, and the its byte size, are saved.The file is closed and is thenimmediatelymoved/renamed into thenew subdirectory.The name of the file innewshould be“time.MusecPpidVdevIino.host,S=cnt”, or“time.MusecPpidVdevIino_unique.host,S=cnt”.“dev” is the message's device number,“ino” is the message's inode number(from the previousfstat(2)call);and“cnt” is the message's size, in bytes.

The“,S=cnt”part optimizes theCourier mail server'smaildir quota enhancement; it allows the size of all the mail stored inthe maildir to be added up without issuing thestat(2)system callfor each individual message (this can be quite a performance drain withcertain network filesystems).

READING MAIL FROM MAILDIRS

Applications that read mail from maildirs should do it in the followingorder:

When opening a maildir or a maildir folder, read thetmpsubdirectory and delete any files in there that are at least 36 hoursold.

Look for new messages in thenew subdirectory.Renamenew/filename,ascur/filename:2,info.Here,info represents the state of the message,and itconsists of zero or more boolean flags chosen from the following:“D” - this is a 'draft' message,“R” - this message has been replied to,“S” - this message has been viewed (seen),“T” - thismessage has been marked to be deleted (trashed), but is not yetremoved (messages are removed from maildirs simply by deleting their file),“F” - this message has been marked by theuser, for some purpose.These flags must be stored in alphabetical order.New messages contain only the:2,suffix, with no flags, indicating that the messages were not seen,replied, marked, or deleted.

Maildirs may have maximum size quotas defined, but these quotas are purelyvoluntary. If you need to implement mandatory quotas, you should use anyquota facilities provided by the underlying filesystem that is used to storethe maildirs. The maildir quota enhancement is designed to be used in certainsituations where filesystem-based quotas cannot be used for some reason. Theimplementation is designed to avoid the use of any locking. As such, atcertain times the calculated quota may be imprecise, and certain anomaloussituations may result in the maildir actually going over the stated quota. Onesuch situation would be when applications create messages without updating thequota estimate for the maildir. Eventually it will be precisely recalculated,but wherever possible new messages should be created in compliance with thevoluntary quota protocol.

The voluntary quota protocol involves some additional procedures that mustbe followed when creating or deleting messages within a given maildir or itssubfolders. Thedeliverquota(8)command is atiny application that delivers a single message to a maildir using thevoluntary quota protocol, and hopefully it can be used as a measure of lastresort. Alternatively, applications can use thelibmaildir.alibrary to handle all the low-level dirty details for them. The voluntaryquota enhancement is described in themaildirquota(7)man page.

Maildir Quotas

This is a voluntary mechanism for enforcing "loose" quotas on the maximumsizes of maildirs. This mechanism is enforced in software, and not by theoperating system. Therefore it is only effective as long as the maildirsthemselves are not directly accessible by their users, since this mechanismis trivially disabled.

If possible, operating system-enforced quotas are preferrable.Where operating system quota enforcement is not available, or not possible,this voluntary quota enforcement mechanism might be an acceptablecompromise. Since it's enforced in software, all software that modifiesor accesses the maildirs is required to voluntary obey and enforce aquota. The voluntary quota implementation is flexible enough to allownon quota-aware applications to also access the maildirs, without anydrastic consequences. There will be some non-drastic consequences, though.Of course, non quota-aware applications will not enforce any defined quotas.Furthermore, this voluntary maildir quota mechanism works by estimating thecurrent size of the maildir, with periodic exact recalculation.Obviously non quota-aware maildir applications will not update the maildirsize estimation, so the estimate will be thrown off for some period of time,until the next recalculation.

This voluntary quota mechanism is designed to be a reasonable compromisebetween effectiveness, and performance. The entire purpose of usingmaildir-based mail storage is to avoid any kind of locking, and to permitparallel access to mail by multiple applications. In order to compute theexact size of a maildir, the maildir must be locked somehow to prevent anymodifications while its contents are added up. Obviously something likethat defeats the original purpose of using maildirs, therefore the voluntaryquota mechanism does not use locking, and that's why the current recordedmaildir size is always considered to be an estimate. Regular sizerecalculations will compensate for any occasional race conditions that resultin the estimate to be thrown off.

A quota for an existing maildir is installed by running maildirmake with the-q option, and naming an existing maildir.The-q option takes a parameter,quota, whichis a comma-separated list of quota specifications. A quota specificationconsists of a number followed by either 'S', indicating the maximum messagesize in bytes, or 'C', maximum number of messages. For example:

This sets the quota to5,000,000 bytes or 1000 messages, whichever comes first.

This sets the quotato 1,000,000 bytes, without limiting the number of messages.

A quota of an existing maildir can be changed by rerunning themaildirmake command with a new-qoption.To delete a quota entirely, delete theMaildir/maildirsizefile.