/usr/share/doc/mailutils-doc/mailutils.html/mailbox-statement.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Published by the Free Software Foundation,
51 Franklin Street, Fifth Floor
Boston, MA 02110-1301, USA

Copyright (C) 1999-2004, 2008-2012, 2014-2016 Free Software
Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover, and no Back-Cover texts.
A copy of the license is included in the section entitled "GNU Free
Documentation License". -->
<!-- Created by GNU Texinfo 6.3, http://www.gnu.org/software/texinfo/ -->
<head>
<title>GNU Mailutils Manual: mailbox statement</title>

<meta name="description" content="GNU Mailutils Manual: mailbox statement">
<meta name="keywords" content="GNU Mailutils Manual: mailbox statement">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Function-Index.html#Function-Index" rel="index" title="Function Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="configuration.html#configuration" rel="up" title="configuration">
<link href="locking-statement.html#locking-statement" rel="next" title="locking statement">
<link href="debug-statement.html#debug-statement" rel="prev" title="debug statement">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
blockquote.smallindentedblock {margin-right: 0em; font-size: smaller}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smalllisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>


</head>

<body lang="en">
<a name="mailbox-statement"></a>
<div class="header">
<p>
Next: <a href="locking-statement.html#locking-statement" accesskey="n" rel="next">locking statement</a>, Previous: <a href="debug-statement.html#debug-statement" accesskey="p" rel="prev">debug statement</a>, Up: <a href="configuration.html#configuration" accesskey="u" rel="up">configuration</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="The-mailbox-Statement"></a>
<h4 class="subsection">3.2.7 The <code>mailbox</code> Statement</h4>
<a name="Mailbox-Statement"></a><a name="index-mailbox"></a>
<a name="Syntax-4"></a>
<h4 class="subheading">Syntax</h4>
<div class="example">
<pre class="example">mailbox {
  # <span class="roman">Use specified <var>url</var> as a mailspool.</span>
  mail-spool <var>url</var>;
  
  # <span class="roman">Create mailbox <var>url</var> using <var>pattern</var>.</span>
  mailbox-pattern <var>pattern</var>;
  
  # <span class="roman">Default mailbox type.</span>
  mailbox-type <var>type</var>;
  
  # <span class="roman">Default user mail folder.</span>
  folder <var>dir</var>;
}
</pre></div>

<a name="Description-2"></a>
<h4 class="subheading">Description</h4>
<p>The <code>mailbox</code> statement configures the location, name and type of
user mailboxes.
</p>
<p>The mailbox location can be specified using <code>mail-spool</code> or
<code>mail-pattern</code> statements.
</p>
<dl>
<dt><a name="index-mail_002dspool"></a>Configuration: <strong>mail-spool</strong> <em><var>path</var></em></dt>
<dd><p>The <code>mail-spool</code> statement specifies directory that holds user
mailboxes.  Once this statement is given, the <code>libmailutils</code>
library will assume that the mailbox of user <var>login</var> is kept in
file <samp><var>path</var>/<var>login</var></samp>.
</p>
<p>Historically, <var>path</var> can contain mailbox type prefix, e.g.:
&lsquo;<samp>maildir:///var/spool/mail</samp>&rsquo;, but such usage is discouraged in
favor of <code>mailbox-pattern</code> statement.
</p></dd></dl>

<dl>
<dt><a name="index-mailbox_002dpattern"></a>Configuration: <strong>mailbox-pattern</strong> <em><var>url</var></em></dt>
<dd><p>The <code>mailbox-pattern</code> statement is a preferred way of configuring
mailbox locations.  It supersedes <code>mail-spool</code> statement.
</p>
<p>The <var>url</var> must be a valid mailbox URL (see <a href="Mailbox.html#Mailbox">Mailbox</a>), which 
may contain references to the &lsquo;<samp>user</samp>&rsquo; variable
(see <a href="Variables.html#Variables">Variables</a>).  This variable will be expanded to the actual
user name.
</p>
<a name="local-URL-parameters"></a><a name="index-directory-indexing"></a>
<p>Optional URL parameters can be used to configure <em>indexed directory
structure</em>.  Such structure is a special way of storing mailboxes,
which allows for faster access in case of very large number of users. 
</p>
<p>By default, all user mailboxes are stored in a single directory and
are named after user login names.  To find the mailbox for a given
user, the system scans the directory for the corresponding
file.  This usually implies linear search, so the time needed to
locate a mailbox is directly proportional to the ordinal number of
the mailbox in the directory.
</p>
<p>GNU Mailutils supports three types of indexed directories:
&lsquo;<samp>direct</samp>&rsquo;, &lsquo;<samp>reverse</samp>&rsquo;, and &lsquo;<samp>hashed</samp>&rsquo;.
</p>
<a name="index-direct-indexing"></a>
<a name="index-indexing_002c-direct"></a>
<p>In direct indexed directory structure, <var>path</var> contains 26 subdirectories
named with lower-case letters of Latin alphabet.  The location of the
user mailbox is determined using the following algorithm:
</p>
<ol>
<li> Take the first letter of the user name.
</li><li> Map it to a lower-case letter using <em>index mapping</em>
table.  The result gives the name of a sub-directory where the mailbox
is located.
</li><li> Descend into this directory.
</li></ol>

<p>For example, using this algorithm, the mailbox of the user
&lsquo;<samp>smith</samp>&rsquo; is stored in file <samp><var>path</var>/s/smith</samp>.
</p>
<p>If each of single-letter subdirectories contains the
indexed directory structure, we have second level of indexing.  In
this case the file name of &lsquo;<samp>smith</samp>&rsquo;&rsquo;s mailbox is
<samp><var>path</var>/s/m/smith</samp>.
</p>
<a name="index-reverse-indexing"></a>
<a name="index-indexing_002c-reverse"></a>
<p>The <em>reverse</em> indexed structure uses the same principles, but the
indexing letters are taken from the <em>end</em> of the user name,
instead of from the beginning.  For example, in the 2nd level reverse
indexed structure, the &lsquo;<samp>smith</samp>&rsquo;&rsquo;s mailbox is located in
<samp><var>path</var>/h/t/smith</samp>.
</p>
<a name="index-hashed-indexing"></a>
<a name="index-indexing_002c-hashed"></a>
<p>Finally, the <em>hashed</em> structure consists of 256 subdirectories
under <var>path</var>, named by 2-letter hex codes from &lsquo;<samp>00</samp>&rsquo; to
&lsquo;<samp>FF</samp>&rsquo;.  Mailboxes are stored in these subdirectories.  The name
of the subdirectory is computed by hashing first <var>level</var> letters
of the user name.  The hashing algorithm is:
</p>
<ol>
<li> Take next letter from the user name
</li><li> Add its ASCII value to the hash sum.
</li><li> Continue (1-2) until <var>level</var> letters are processed, or all
letters from the file name are used, whichever occurs first.
</li><li> Convert the computed sum modulo 256 to a hex code.
</li></ol>

<p>Indexed directory structures are configured using the following
arguments:
</p>
<dl compact="compact">
<dd><a name="index-type"></a>
</dd>
<dt>type=<var>value</var></dt>
<dd><p>Specifies the type of indexing.  Valid values are &lsquo;<samp>index</samp>&rsquo;, for direct
indexed structure, &lsquo;<samp>rev-index</samp>&rsquo; for reverse indexing, and
&lsquo;<samp>hash</samp>&rsquo; for hashed structure.
</p>
<a name="index-param"></a>
</dd>
<dt>param=<var>number</var></dt>
<dd><p>Specifies indexing level.
</p>
<a name="index-user-1"></a>
</dd>
<dt>user=<var>string</var></dt>
<dd><p>Specifies indexing key.  The only meaningful value, as of Mailutils
version 3.1.1 is &lsquo;<samp>user=${user}</samp>&rsquo;.
</p></dd>
</dl>

<p>Let&rsquo;s assume the traditional mail layout, in which incoming
mails are stored in a UNIX mailbox named after the recipient user name
and located in <samp>/var/mail</samp> directory.
The <code>mailbox-pattern</code> for this case is:
</p>
<div class="example">
<pre class="example">  mailbox-pattern &quot;/var/mail/${user}&quot;;
</pre></div>

<p>It is entirely equivalent to specifying &lsquo;<samp>mail-spool &quot;/var/mail&quot;</samp>&rsquo;.
</p>
<p>Now, if the layout is the same, but mailboxes are kept in
&lsquo;<samp>maildir</samp>&rsquo; format, then the corresponding statement is:
</p>
<div class="example">
<pre class="example">  mailbox-pattern &quot;maildir:///var/mail/${user}&quot;;
</pre></div>

<p>Finally, if the mailboxes are stored in a directly-indexed directory with
two levels of indexing, the URL is:
</p>
<div class="example">
<pre class="example">  mailbox-pattern &quot;maildir:///var/mail;type=index;param=2;user=${user}&quot;;
</pre></div>
</dd></dl>

<p>If neither <code>mailbox-pattern</code> nor <code>mail-spool</code> are given, the
mailbox names are determined using the following algorithm:
</p>
<ol>
<li> If environment variable <code>FOLDER</code> is set, use its value.
</li><li> Otherwise, if environment variable <code>MAIL</code> is set, use its
value.
</li><li> If neither of these is set, construct the mailbox name by 
concatenating the built-in mail spool directory name, a directory
separator, and the user name.

<p>The built-in mail spool directory name is determined at compile
time, using the &lsquo;<samp>_PATH_MAILDIR</samp>&rsquo; define from the include file
<samp>paths.h</samp>.  If this value is not defined, <samp>/var/mail</samp> or
<samp>/usr/spool/mail</samp> is used.
</p></li></ol>

<dl>
<dt><a name="index-mailbox_002dtype"></a>Configuration: <strong>mailbox-type</strong> <em><var>type</var></em></dt>
<dd><a name="index-MU_005fDEFAULT_005fSCHEME"></a>
<p>Specifies the type of mailboxes.  By default, &lsquo;<samp>mbox</samp>&rsquo; (UNIX mailbox)
is assumed.  This can be changed while configuring the package by
setting <code>MU_DEFAULT_SCHEME</code> configuration variable.  The default
value can be verified by running <code>mailutils info scheme</code>.
</p></dd></dl>

<dl>
<dt><a name="index-folder"></a>Configuration: <strong>folder</strong> <em><var>dir</var></em></dt>
<dd><a name="index-plus-expansion"></a>
<p>Sets user mail folder directory.  Its value is used when expanding
&lsquo;<samp>plus-notation</samp>&rsquo;, i.e. such mailbox names as <samp>+inbox</samp>.  The
&lsquo;<samp>+</samp>&rsquo; sign is replaced by <var>dir</var>, followed by a directory
separator (&lsquo;<samp>/</samp>&rsquo;).
</p>
<p>The <var>dir</var> argument can contain mailbox type prefix, e.g
&lsquo;<samp>mh://Mail</samp>&rsquo;.
</p>
<p>The default folder name is &lsquo;<samp>Mail/</samp>&rsquo;.
</p></dd></dl>

<hr>
<div class="header">
<p>
Next: <a href="locking-statement.html#locking-statement" accesskey="n" rel="next">locking statement</a>, Previous: <a href="debug-statement.html#debug-statement" accesskey="p" rel="prev">debug statement</a>, Up: <a href="configuration.html#configuration" accesskey="u" rel="up">configuration</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Function-Index.html#Function-Index" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
mailutils-doc 1:3.1.1-1 / usr / share / doc / mailutils-doc / mailutils.html / mailbox-statement.html
