NAME

       mh-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 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 a 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 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 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 nonexistant 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 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 ALSO

       flist(1),   folder(1),   mail(1),   mark(1),   mh-param(1),   mh-path(1),   mh-profile(5),
       mh-sequence(5), pick(1), rcvstore(1)