1MH-FOLDERS(5) File Formats Manual MH-FOLDERS(5)
2
6 mh-folders - storage format used by nmh message system
7
9 nmh stores messages in the files and directories of the host filesystem
10 according to the following rules:
11 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 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 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 To add a new message to a folder, the recommended sequence is:
32 • Create a temporary file in the desired folder.
34 • Attempt to link the temporary file to the new message number.
36 • 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 Current-Folder: +folder
46 atr-sequence-path: m[-n] [...]
47 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 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 sequence: m[-n] [...]
60 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 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 If an implementation finds messages in a sequence that do not ex‐
71 ist, 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 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 A second, possibly different, locking method is used by inc(1) when ac‐
89 cessing 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 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 -- al‐
101 lowing folders to be named similarly would make nmh slower, and intro‐
102 duce usage ambiguities.
103
105 <mh-dir>/context The user's context.
106 $MHCONTEXT Overrides the above context.
107 <folder>/.mh-sequences
108 Public sequences for <folder>.
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)
112nmh-1.8 2016-02-25 MH-FOLDERS(5)