phpman > man > mh-folders(5)

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.7.1                                    2016-02-25                              MH-FOLDERS(5mh)