doc/maildir.html

   1 <html><head>
   2 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   3 </head><body>
   4 <a href="http://cr.yp.to/djb.html">D. J. Bernstein</a>
   5 <br><a href="http://cr.yp.to/mail.html">Internet mail</a>
   6 <h1>Using maildir format</h1>
   7 <h2>Why should I use maildir?</h2>
   8 Two words: <b>no locks</b>.
   9 An MUA can read and delete messages while new mail is being delivered:
  10 each message is stored in a separate file with a unique name,
  11 so it isn't affected by operations on other messages.
  12 An MUA doesn't have to worry about partially delivered mail:
  13 each message is safely written to disk in the <b>tmp</b> subdirectory
  14 before it is moved to <b>new</b>.
  15 The maildir format is reliable even over NFS.
  16 <h2>How are unique names created?</h2>
  17 Unless you're writing messages to a maildir,
  18 the format of a unique name is none of your business.
  19 A unique name can be anything
  20 that doesn't contain a colon (or slash)
  21 and doesn't start with a dot.
  22 Do not try to extract information from unique names.
  23 <p>
  24 Okay, so you're writing messages.
  25 A unique name has three pieces, separated by dots.
  26 On the left is the result of time() or the second counter from gettimeofday().
  27 On the right is the result of gethostname().
  28 (To deal with invalid host names,
  29 replace / with \057 and : with \072.)
  30 In the middle is a delivery identifier, discussed below.
  31 </p><p>
  32 As the terminology suggests,
  33 <b>every delivery to this maildir must have its own unique name</b>.
  34 When a maildir is shared through NFS,
  35 every machine that delivers to the maildir <b>must</b> have its own hostname.
  36 Within one machine,
  37 every delivery within the same second
  38 <b>must</b> have a different delivery identifier.
  39 </p><p>
  40 Modern delivery identifiers are created by concatenating
  41 enough of the following strings to guarantee uniqueness:
  42 </p><ul>
  43 <li>#<i>n</i>,
  44 where <i>n</i> is (in hexadecimal) the output of
  45 the operating system's unix_sequencenumber() system call,
  46 which returns a number that increases by 1 every time it is called,
  47 starting from 0 after reboot.
  48 </li><li>X<i>n</i>,
  49 where <i>n</i> is (in hexadecimal) the output of
  50 the operating system's unix_bootnumber() system call,
  51 which reports the number of times that the system has been booted.
  52 Together with #, this guarantees uniqueness;
  53 unfortunately, most operating systems don't support
  54 unix_sequencenumber() and unix_bootnumber.
  55 </li><li>R<i>n</i>,
  56 where <i>n</i> is (in hexadecimal) the output of
  57 the operating system's unix_cryptorandomnumber() system call,
  58 or an equivalent source such as /dev/urandom.
  59 Unfortunately,
  60 some operating systems don't include cryptographic random number generators.
  61 </li><li>I<i>n</i>,
  62 where <i>n</i> is (in hexadecimal) the UNIX inode number of this file.
  63 Unfortunately, inode numbers aren't always available through NFS.
  64 </li><li>V<i>n</i>,
  65 where <i>n</i> is (in hexadecimal) the UNIX device number of this file.
  66 Unfortunately, device numbers aren't always available through NFS.
  67 (Device numbers are also not helpful with the standard UNIX filesystem:
  68 a maildir has to be within a single UNIX device
  69 for link() and rename() to work.)
  70 </li><li>M<i>n</i>,
  71 where <i>n</i> is (in decimal) the microsecond counter
  72 from the same gettimeofday() used for the left part of the unique name.
  73 </li><li>P<i>n</i>,
  74 where <i>n</i> is (in decimal) the process ID.
  75 </li><li>Q<i>n</i>,
  76 where <i>n</i> is (in decimal) the number of deliveries made by this process.
  77 </li></ul>
  78 Old-fashioned delivery identifiers use the following formats:
  79 <ul>
  80 <li><i>n</i>, where <i>n</i> is the process ID,
  81 and where this process has been forked to make one delivery.
  82 Unfortunately,
  83 some foolish operating systems repeat process IDs quickly,
  84 breaking the standard time+pid combination.
  85 </li><li><i>n</i>_<i>m</i>, where <i>n</i> is the process ID
  86 and <i>m</i> is the number of deliveries made by this process.
  87 </li></ul>
  88 <h2>What can I put in info?</h2>
  89 When you move a file from <b>new</b> to <b>cur</b>,
  90 you have to change its name from <i>uniq</i> to <i>uniq:info</i>.
  91 Make sure to preserve the <i>uniq</i> string,
  92 so that separate messages can't bump into each other.
  93 <p>
  94 <i>info</i> is morally equivalent to the Status field used by mbox readers.
  95 It'd be useful to have MUAs agree on the meaning of <i>info</i>,
  96 so I'm keeping a list of <i>info</i> semantics.
  97 Here it is.
  98 </p><p>
  99 <i>info</i> starting with "1,": Experimental semantics.
 100 </p><p>
 101 <i>info</i> starting with "2,":
 102 Each character after the comma is an independent flag.
 103 </p><ul>
 104 <li>Flag "P" (passed): the user has resent/forwarded/bounced this message
 105 to someone else.
 106 </li><li>Flag "R" (replied): the user has replied to this message.
 107 </li><li>Flag "S" (seen): the user has viewed this message, though perhaps
 108 he didn't read all the way through it.
 109 </li><li>Flag "T" (trashed): the user has moved this message to the trash;
 110 the trash will be emptied by a later user action.
 111 </li><li>Flag "D" (draft): the user considers this message a draft;
 112 toggled at user discretion.
 113 </li><li>Flag "F" (flagged): user-defined flag; toggled at user discretion.
 114 </li></ul>
 115 New flags may be defined later.
 116 Flags must be stored in ASCII order: e.g., "2,FRS".
 117 <h2>Can a maildir contain more than tmp, new, cur?</h2>
 118 Yes:
 119 <ul>
 120 <li>.qmail: used to do direct deliveries with qmail-local.
 121 </li><li>bulletintime: empty file, used by system-wide bulletin programs.
 122 </li><li>bulletinlock: empty file, used by system-wide bulletin programs.
 123 </li><li>seriallock: empty file, used to serialize AutoTURN.
 124 </li></ul>
 125 </body></html>