1MH-FOLDERS(5)                 File Formats Manual                MH-FOLDERS(5)
2
3
4

NAME

6       mh-folders - storage format used by nmh message system
7

DESCRIPTION

9       nmh stores messages in the files and directories of the host filesystem
10       according to the following rules:
11
12       one folder per directory
13            An nmh folder corresponds to a directory.  There are no limits  on
14            folder names beyond those of the host filesystem.
15
16       one message per file
17            The file name is a positive integer.  Other files containing meta‐
18            data or arbitrary names can exist in a folder; while  the  prefer‐
19            ence  is that non-message files begin with “.”, all files that are
20            not positive integers must be ignored by an  MH-compatible  imple‐
21            mentation.   However,  implementations are free to indicate to the
22            user the existence of non-message files that are not prefixed with
23            a “.”.
24
25            The  filename  for  a  new message is one greater than the highest
26            numbered message in the folder; its full path can be  accessed  by
27            the pseudo-sequence new (e.g., mhpath new).  New messages are only
28            permitted to be added to a folder at the end of the message number
29            range.
30
31            To add a new message to a folder, the recommended sequence is:
32
33            ·   Create a temporary file in the desired folder.
34
35            ·   Attempt to link the temporary file to the new message number.
36
37            ·   If  successful, remove the temporary file.  If the link fails,
38                increment the message number and try again.
39       context
40            There is one context file.  Its default location is in the  user's
41            Path  and its default name is context, but these can be overridden
42            by the $MHCONTEXT environment variable.  context has the following
43            format:
44
45                 Current-Folder: +folder
46                 atr-sequence-path: m[-n] [...]
47
48            where  folder  is the directory name of the current folder.  Lines
49            beginning with “atr” are used for private sequences.  sequence  is
50            the  name  of  the  private sequence, path is the full path to the
51            folder with the private sequence, and m[-n] is a message number or
52            range of message numbers in the sequence.
53
54       sequences
55            There  is one sequences file in each nmh folder.  Its default name
56            is .mh_sequences, but this can be overridden by the “mh-sequences”
57            profile entry.  sequences has the following format:
58
59                 sequence: m[-n] [...]
60
61            showing the (possibly empty) message numbers and/or ranges of mes‐
62            sage numbers in each sequence.  The cur sequence has at most  just
63            a single message number, not a range.
64
65            Sequence  names  have a maximum size of 998 characters.  Each line
66            is also limited to a maximum of 998 characters, but RFC  822  con‐
67            tinuation  rules apply; sequences can be continued across multiple
68            lines by prefixing continuation lines with a whitespace character.
69
70            If an implementation finds messages in  a  sequence  that  do  not
71            exist,  the  sequence file should be updated to remove the missing
72            messages from the sequence.  If a sequence contains  no  messages,
73            it  should  be  removed  from the sequence file.  The exception to
74            this is the cur sequence, which can refer to  a  nonexistent  mes‐
75            sage.
76
77   Locking
78       nmh  programs  read and write the context and sequences files, and lock
79       these files when accessing them.  There should not be a need to  access
80       these  files  directly;  instead, programs such as flist, folder, mark,
81       pick, and rcvstore should be used to query and update  their  contents.
82       Any  program  outside  of nmh that accesses these files must be sure to
83       lock them using the same locking method as nmh.  The default data lock‐
84       ing  method is selected when nmh is configured and can be accessed as a
85       string using mhparam datalocking.  By default, fcntl locking  is  used,
86       but this may be overridden by the datalocking profile entry.
87
88       A  second,  possibly  different,  locking method is used by inc(1) when
89       accessing the user's mail spool file or by nmh programs that  open  any
90       mbox  file.   This locking method can be overridden when nmh is config‐
91       ured, or in the nmh mts configuration file, and can be  accessed  as  a
92       string using mhparam spoollocking.  By default, kernel-level locking is
93       used if appropriate for the platform, and it is for popular  platforms.
94       That  default  should  also be the same as used by the mail program, if
95       provided on the platform.
96
97   Naming
98       nmh folders can be given arbitrary names, with one  exception:  folders
99       should  not  be  given all-numeric names.  This limitation results from
100       nmh messages themselves being stored  in  numerically  named  files  --
101       allowing  folders  to  be  named  similarly  would make nmh slower, and
102       introduce usage ambiguities.
103

FILES

105       <mh-dir>/context    The user's context.
106       $MHCONTEXT          Overrides the above context.
107       <folder>/.mh-sequences
108                           Public sequences for <folder>.

SEE ALSO

110       flist(1), folder(1), mail(1), mark(1), mhparam(1),  mhpath(1),  mh-pro‐
111       file(5), mh-sequence(5), mh-tailor(5), pick(1), rcvstore(1)
112
113
114
115nmh-1.7.1                         2016-02-25                     MH-FOLDERS(5)
Impressum