WEB邮件程序

开发平台：
C/C++

maildirmake.html.in：源码内容
							<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
                      "http://www.w3.org/TR/REC-html40/loose.dtd">
<html>
<head>
  <title>maildirmake - create maildirs, and maildir folders</title>
  <!-- $Id: maildirmake.html.in,v 1.1 2000/05/07 17:14:24 mrsam Exp $ -->
  <!-- Copyright 1998 - 2000 Double Precision, Inc.  See COPYING for -->
  <!-- distribution information. -->
  <!-- SECTION 1 -->
  <meta http-equiv="Content-Type" content="text/html">
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink="#551A8B"
alink="#FF0000">
<h1>maildirmake - create maildirs, and maildir folders</h1>
<h2>SYNOPSIS</h2>
<pre>maildirmake [ options ] <i>maildir</i></pre>
<h2>DESCRIPTION</h2>
<p>The <code>maildirmake</code> command is used to create Maildirs, and
Maildir folders.  This <code>maildirmake</code> command also creates several
extensions to the base Maildir format.</p>
<p>A Maildir is a directory that's used to store mail messages.  Not just any
directory will do - a Maildir must be of a specific structure, and have
specific access permissions.  The <code>maildirmake</code> command is a
convenient way to create a new Maildir, or a new folder within an existing
Maildir, with the correct permission and structure.</p>
<h2>OPTIONS</h2>
<ul>
  <li><code>-S</code> - create a "sharable" maildir.  A sharable maildir has
    slightly different permissions which allows creating publicly-shared
    folders.<br>
    <br>
  </li>
  <li><code>-f folder</code> - do not create a maildir, but create a folder in
    an existing maildir.<br>
    <br>
  </li>
  <li><code>-s <i>mode</i></code> - create a publicly accessible folder in an
    existing sharable maildir.  First, use the <code>-S</code> option to
    create a sharable maildir, then use the <code>-s</code> option to create
    publicly accessible folders. "<i>mode</i>" is a comma-separated list of
    the following keywords: <code>read</code> - readonly folder, only you can
    write messages to this folder; <code>write</code> - anyone can read and
    write messages to this folder; <code>group</code> - only allow members of
    your own system group to access messages in this folder (instead of
    everyone).<br>
    <br>
  </li>
  <li><code>--add <i>name=/shared/maildir/path</i></code>, <code>--del
    <i>name</i></code> - create or delete the directories and links needed to
    access shared folders.  See below for more information.</li>
</ul>
<h2>FOLDERS</h2>
<p>This <code>maildirmake</code> command supports enhanced maildirs that
contain folders.</p>
<p>By itself, <code>maildirmake</code> makes a new subdirectory
<i>maildir</i>, and creates all the necessary structures. The -f option
creates a new "folder" within an existing <i>maildir</i>. <i>maildir</i> must
already exist, and the <code>maildirmake</code> command will create a new
folder inside it.</p>
<p>Folders are simply subdirectories inside the main maildir whose names start
with a period, and which are themselves maildirs. For example, the command
"<code>maildirmake -f Drafts mail/Maildir</code>" creates
<code>mail/Maildir/.Drafts</code>, with the usual <code>tmp</code>,
<code>new</code>, and <code>cur</code>. You MUST use the -f option, instead of
specifying <code>mail/Maildir/.Drafts</code> directly, in order to correctly
initialize certain enhanced maildir features.</p>
<p>Folders cannot be created directly within other folders.  Running
<code>maildirmake -f Urgent mail/Maildir/.Drafts</code> will not work.
Instead, the period character is designated as a hierarchy separator, run
<code>maildirmake -f Drafts.Urgent mail/Maildir</code> instead. This creates
<code>mail/Maildir/.Drafts.Urgent</code>, and all mail software that supports
enhanced maildirs will interpret it as a subfolder Urgent of the Drafts
folder.</p>
<h2>SHARED FOLDERS</h2>
<p>This is another extension to the Maildir format that allows folders to be
shared between multiple clients.  First, you need to create a collection of
sharable folders, as a separate maildir:</p>
<pre>   maildirmake -S /usr/local/share/maildirs/notices</pre>
<p>Then, you create individuals folders that will be accessed in shared
mode:</p>
<pre>   maildirmake -s write -f Weekly /usr/local/share/maildirs/notices</pre>
<p>The "Weekly" folder is created, with read/write access to everyone.
Multiple folders can be created in the same maildir, with different access
permissions. Everyone can create a sharable maildir.  The access privileges
for individual folders are set by the <code>-s</code> option, and are
implemented using traditional filesystem permissions.</p>
<p>Use the <i>--add</i> and <i>--del</i> options to add a sharable maildir to
an existing maildir.  Client software that implement this extension will now
know where to find sharable folders:</p>
<pre>   maildirmake --add notices=/usr/local/share/maildirs/notices $HOME/Maildir</pre>
<i>$HOME/Maildir</i> is your main maildir. The argument to <code>-add</code>
is <i>nick=path</i>. <i>nick</i> is the nickname you give to the collection of
all the sharable folders, and <i>path</i> is the location of the sharable
maildir. All folders in the sharable maildir that you have access to -- such
as "Weekly", in this case, will now be accessible by compliant software.
Multiple sharable maildirs can be added, by giving each one a unique name.
<p>The <code>--del</code> option "disconnects" the sharable maildir from your
main maildir.</p>
<h2>GLOBAL SHARED FOLDERS</h2>
<p>Normally the <i>-add</i> command must be run for every maildir which needs
to access a sharable maildir. Alternatively the file
<code>@sysconfdir@/maildirshared</code> can be created, which will be used for
a default set of sharable maildirs. Each line in this file takes the following
form:</p>
<pre>      nick&lt;tab>path</pre>
<p><i>nick</i> is a short nickname for the sharable maildir, <i>&lt;tab></i>
is a single tab character, <i>path</i> is the pathname to the sharable
maildir.</p>
<h2>ACCESSING SHARED FOLDERS</h2>
<p>You may have read or write access to a shared folder. If you have write
access, you can add messages to the shared folder. You can also delete
messages that you've added, but nobody else's.</p>
<p>Anyone can create a sharable maildir, so if the sharable maildir is
actually created by you, can can delete any message, not just your own.</p>
<h2>MAILDIR STRUCTURE</h2>
<p>The rest of this manual page is a technical description of Maildirs. The
first implementation and definition of Maildirs were in Dan Bernstein's Qmail
mail server, and it described a single, flat, mail repository.  Since then,
independent developers added additional features on top of it, such as folders
and voluntary mail quotas.  This document describes the enhanced Maildir
implementation without noting the specific enhancements to the original
Maildir implementation. See <a
href="http://www.qmail.org/man/man5/maildir.html">http://www.qmail.org/man/man5/maildir.html</a>
for the original specifications of Maildirs.</p>
<p>Maildirs offer several improvements over traditional mailbox files. Unlike
mailbox files, no locking is necessary in order to deliver new messages to
maildirs, or to read mail in maildirs.  Multiple agents can deliver new mail
to maildirs, in parallel, and read mail from maildirs.  Locking is often
problematic with certain network file system.  Maildirs require no locking,
and can be implemented on top of almost any file system.</p>
<p>A maildir is an ordinary subdirectory, with group and world access
permissions revoked, of course.  A maildir contains three subdirectories:
<code>tmp</code>, <code>new</code>, and <code>cur</code>. Folders are
additional subdirectories whose names begin with a period: such as
<code>.Drafts</code> or <code>.Sent</code>.  Each folder itself contains the
same three subdirectories, <code>tmp</code>, <code>new</code>, and
<code>cur</code>, and can be thought of as a maildir in of itself, except that
it itself cannot contain nested folder subdirectories, as explained above.</p>
<p>A folder subdirectory also contains an extra, zero-length file named
<code>maildirfolder</code>, whose purpose is to simply inform any mail
delivery agent that it really is delivery directly to a subfolder, and that
the mail delivery agent should look in the parent directory for any required
housekeeping information. Software that uses maildirs may also create
additional files besides the <code>tmp</code>, <code>new</code>, and
<code>cur</code> subdirectories -- in the main maildir or a folder
"submaildir" -- for their own use.</p>
<p>E-mail messages are stored in separate, individual files as defined below,
one E-mail message per file. The <code>tmp</code> subdirectories is used to
temporarily store E-mail messages that are in the process of being delivered
to this maildir.  It can also be used for storing other kinds of temporary
files, as long as they follow the same naming convention for creating new
files in <code>tmp</code>. The <code>new</code> subdirectory stores messages
that have been delivered to this maildir, but have not yet been seen by any
mail application. The <code>cur</code> subdirectory stores messages that have
already been seen by mail applications.</p>
<h2>DELIVERING NEW MAIL TO A MAILDIR</h2>
<p>The following process is used to deliver mail to a maildir:</p>
<p>A new unique filename is created using one of two possible forms:
"time.pid.host", or "time.pid_unique.host".  "time" is the current system
time, in seconds.  "pid" is the process number of the process that is
delivering this message to the maildir. "host" is the name of the machine
where the mail is being delivered.  In the event that the same process will
create multiple messages, it should append a unique suffix to the process id,
preferrably an underscore, followed by an increasing counter. This applies
whether messages created by a process are all in the same, or different,
maildirs. This protocol allows multiple processes running on multiple machines
on the same network to simultaneously create new messages without stomping on
each other.</p>
<p>The filename created in the previous step is checked for existence by
executing the <i>stat(2)</i> system call, against the <code>tmp</code>
subdirectory.  If the result of the <i>stat</i> system call is ANYTHING OTHER
than the system error <code>ENOENT</code>, the process must sleep for two
seconds, then go back and create a new unique filename.  This is an extra step
to insure that each new message has a completely unique filename.</p>
<p>Other applications that wish to use <code>tmp</code> for temporary storage
should observe the same protocol (but see READING MAIL FROM MAILDIRS below,
because old files in <code>tmp</code> will be eventually deleted).</p>
<p>If the <i>stat</i> system call returned <code>ENOENT</code>, the process
can go ahead, create the file in the <code>tmp</code> subdirectory, and save
the entire message in the new file.  The message saved MUST NOT have the
traditional "From_" line that is used to separate individual messages in the
traditional mailbox files.  The message also MUST NOT have any "From_" lines
in the contents of the message prefixed by the ">" character, as messages in
traditional mailbox files are.</p>
<p>Saving the message means to reliably save it in a file.  The number of
bytes returned by the <code>write</code> system call must be checked, in order
to make sure that the complete message has been written out.</p>
<p>After the message is saved, the file is closed and is then immediately
moved/renamed into the <code>new</code> subdirectory.  The name of the file
should be the same name it had in the <code>tmp</code> subdirectory.</p>
<p>It is HIGHLY RECOMMENDED that new implementations of software that creates
messages in maildirs would also append the suffix ",S=nnn" to the name of the
file when it is moved into the <code>new</code> subdirectory, where "nnn"
represents the size of the message, in bytes.  This optimizes the voluntary
maildir quota enhancement, as it permits the size of all the mail stored in
the maildir to be added up without issuing the <code>stat</code> system call
for each individual message (which can be quite a performance drain with
certain network filesystems).</p>
<h2>READING MAIL FROM MAILDIRS</h2>
<p>Applications that read mail from maildirs should do it in the following
order:</p>
<p>When opening a maildir or a maildir folder, read the <code>tmp</code>
subdirectory and delete anything in there that's at least 36 hours old.</p>
<p>Look for new messages in the <code>new</code> subdirectory.  For each new
message found, <i>new/filename</i>, rename it as <i>cur/filename:2,info</i>,
where <i>info</i> is used to represent the state of the message, and it
consists of zero or more boolean flags chosen from the following: R - this
message has been replied to, S - this message has been viewed (seen), T - this
message has been marked to be deleted (trashed), but is not yet completely
removed (messages are removed from maildirs simply by deleting their file), F
- this message has been marked by the user, for some purpose. These flags must
be stored in alphabetic order.  New messages contain only the <i>:2,</i>
suffix, with no flags, indicating that the messages haven't been seen,
replied, marked, or deleted.</p>
<p>Maildirs may have maximum size quotas defined, but these quotas are purely
voluntary.  If you need to implement mandatory quotas, you should use any
quota facilities provided by the underlying filesystem that is used to store
the maildirs.  The maildir quota enhancement is designed to be used in certain
situations where filesystem-based quotas cannot be used for some reason.  The
implementation is designed to avoid the use of any locking.  As such, at
certain times the calculated quota may be imprecise, and certain anomalous
situations may result in the maildir actually going over the stated quota. One
such situation would be when applications create messages without updating the
quota estimate for the maildir.  Eventually it will be precisely recalculated,
but wherever possible new messages should be created in compliance with the
voluntary quota protocol.</p>
<p>The voluntary quota protocol involves some additional procedures that must
be followed when creating or deleting messages within a given maildir or its
subfolders.  The <a href="maildirquota.html">deliverquota(8)</a> command is a
tiny application that delivers a single message to a maildir using the
voluntary quota protocol, and hopefully it can be used as a measure of last
resort.  Alternatively, applications can use the <code>libmaildir.a</code>
library to handle all the low-level dirty details for them. The voluntary
quota enhancement is specified in a separate README.</p>
<h2>SEE ALSO</h2>
<a href="maildrop.html">maildrop(1),</a> <a
href="maildirquota.html">maildirquota(8),</a> <a
href="deliverquota.html">deliverquota(8),</a> <a
href="maildropfilter.html">maildropfilter(1)</a>, <a
href="http://www.qmail.org/man/man5/maildir.html">http://www.qmail.org/man/man5/maildir.html</a>,
maildir(5).</body>
</html>

						