phpMan > info > 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 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 meta-
            data or arbitrary names can exist in a folder; while  the  prefer-
            ence  is that non-message files begin with ".", all files that are
            not positive integers must be ignored by an  MH-compatible  imple-
            mentation.   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:

            o   Create a temporary file in the desired folder.

            o   Attempt to link the temporary file to the new message number.

            o   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 mes-
            sage 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  con-
            tinuation  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  ex-
            ist,  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  mes-
            sage.

   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 lock-
       ing  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 ac-
       cessing the user's mail spool file or by nmh  programs  that  open  any
       mbox  file.   This locking method can be overridden when nmh is config-
       ured, 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 --  al-
       lowing  folders to be named similarly would make nmh slower, and intro-
       duce 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-pro-
       file(5), mh-sequence(5), mh-tailor(5), pick(1), rcvstore(1)

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