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) 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),  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)