man > mh-folders(5mh)

MH-FOLDERS(5mh)                                                                      MH-FOLDERS(5mh)

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 fol‐
       lowing 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 implementa‐
            tion.   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 con‐
            tinued across multiple lines by prefixing continuation lines with a  whitespace  charac‐
            ter.

            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  con‐
            tains  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  ac‐
       cessing  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 con‐
       tents.  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 con‐
       figured 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) 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  nu‐
       merically  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), folder(1), mail(1), mark(1), mhparam(1), mhpath(1), mh-profile(5),  mh-sequence(5),
       mh-tailor(5), pick(1), rcvstore(1)

nmh-1.8                                      2016-02-25                              MH-FOLDERS(5mh)