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)