---
name: "mh-folders"
section: "5mh"
platform: "linux"
package: "nmh"
version: "1.8-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mh-folders"
---

# mh-folders(5mh)

storage format used by nmh message system

## NAME

mh-folders - 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**

An **nmh** folder corresponds to a 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 metadata or arbitrary names can exist in a folder; while the preference is that non-message files begin with “.”, all files that are not positive integers *must* be ignored by an **MH**-compatible implementation.  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 its default name is *context*, but these can be overridden by 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 this can be overridden by the “mh-sequences” profile entry. **sequences** has the following format:

**sequence:** *m\[-n\] \[...\]*

showing the (possibly empty) message numbers and/or ranges of message 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 continuation 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 nonexistent message.

### 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 locking 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 by the **datalocking** profile entry.

A second, possibly different, locking method is used by [*inc*(1)](/inc/1.md) when accessing the user's mail spool file or by **nmh** programs that open any mbox file.  This locking method can be overridden when **nmh** is configured, or in the **nmh** mts configuration file, 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.

### Naming

**nmh** folders can be given arbitrary names, with one exception: folders should not be given all-numeric names.  This limitation results from **nmh** messages themselves being stored in numerically named files -- allowing folders to be named similarly would make **nmh** slower, and introduce usage ambiguities.

## FILES

- \<mh-dir\>/context

  The user's context.

- $MHCONTEXT

  Overrides the above context.

- \<folder\>/.mh-sequences

  Public sequences for \<folder\>.

## SEE ALSO

[*flist*(1)](/flist/1.md), [*folder*(1)](/folder/1.md), [*mail*(1)](/mail/1.md), [*mark*(1)](/mark/1.md), [*mhparam*(1)](/mhparam/1.md), [*mhpath*(1)](/mhpath/1.md), [*mh-profile*(5)](/mh-profile/5.md), [*mh-sequence*(5)](/mh-sequence/5.md), [*mh-tailor*(5)](/mh-tailor/5.md), [*pick*(1)](/pick/1.md), [*rcvstore*(1)](/rcvstore/1.md)