MH-FOLDERS(5)MH-FOLDERS(5)NAMEmh-folders - specification of storage format used by nmh message system
DESCRIPTION
nmh stores messages in the files and directories of the host filesystem
according to the following rules:
one folder per directory
A nmh folder corresponds to directory. There are no limits on
folder names beyond those of the host filesystem.
one message per file
The file name is a positive integer. Other files containing meta‐
data or arbitrary names can exist in a folder; while the prefer‐
ence is that non-message files begin with “.”, all files that are
not positive integers must be ignored by a MH-compatible implemen‐
tation. However, implementations are free to indicate to the user
the existence of non-message files that are not prefixed with a
“.”.
The filename for a new message is one greater than the highest
numbered message in the folder; its full path can be accessed by
the pseudo-sequence new (e.g., mhpath new). New messages are only
permitted to be added to a folder at the end of the message number
range.
To add a new message to a folder, the recommended sequence is:
· Create a temporary file in the desired folder.
· Attempt to link the temporary file to the new message number.
· If successful, remove the temporary file. If the link fails,
increment the message number and try again.
context
There is one context file. Its default location is in the user's
Path and default name is context, but those can be overridden with
the $MHCONTEXT environment variable. context has the following
format:
Current-Folder: +folder
atr-sequence-path: m[-n] [...]
where folder is the directory name of the current folder. Lines
beginning with “atr” are used for private sequences. sequence is
the name of the private sequence, path is the full path to the
folder with the private sequence, and m[-n] is a message number or
range of message numbers in the sequence.
sequences
There is one sequences file in each nmh folder. Its default name
is .mh_sequences, but that can be overridden with the
“mh-sequences” profile entry. sequences has the following format:
sequence: m[-n] [...]
showing the (possibly empty) message numbers and/or ranges of mes‐
sage numbers in each sequence. The cur sequence has at most just
a single message number, not a range.
Sequence names have a maximum size of 998 characters. Each line
is also limited to a maximum of 998 characters, but RFC 822 con‐
tinuation rules apply; sequences can be continued across multiple
lines by prefixing continuation lines with a whitespace character.
If an implementation finds messages in a sequence that do not
exist, the sequence file should be updated to remove the missing
messages from the sequence. If a sequence contains no messages,
it should be removed from the sequence file. The exception to
this is the cur sequence, which can refer to a nonexistant mes‐
sage.
Locking
nmh programs read and write the context and sequences files, and lock
these files when accessing them. There should not be a need to access
these files directly; instead, programs such as flist, folder, mark,
pick, and rcvstore should be used to query and update their contents.
Any program outside of nmh that accesses these files must be sure to
lock them using the same locking method as nmh. The default data lock‐
ing method is selected when nmh is configured and can be accessed as a
string using mhparam datalocking. By default, fcntl locking is used,
but this may be overridden with the datalocking profile entry.
A second, possibly different, locking method is used by inc(1) when
accessing the user's mail spool file or by nmh programs that open any
mbox file. This locking method is selected when nmh is configured and
can be accessed as a string using mhparam spoollocking. By default,
kernel-level locking is used if appropriate for the platform, and it is
for popular platforms. That default should also be the same as used by
the mail program, if provided on the platform.
FILES
<mh-dir>/context The user context
or $MHCONTEXT Rather than the standard context
<folder>/.mh_sequences Public sequences for <folder>
SEE ALSOflist(1), folder(1), mail(1), mark(1), mh-param(1), mh-path(1), mh-pro‐
file(5), mh-sequence(5), pick(1), rcvstore(1)nmh-1.6 February 26, 2014 MH-FOLDERS(5)
