1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
.TH MH-FOLDERS %manext5% 2016-02-25 "%nmhversion%"
.
.\" %nmhwarning%
.
.SH NAME
mh-folders \- storage format used by nmh message system
.SH DESCRIPTION
.B nmh
stores messages in the files and directories of the host filesystem
according to the following rules:
.PP
.B one folder per directory
.RS 5
An
.B nmh
folder corresponds to a directory. There are no limits on folder
names beyond those of the host filesystem.
.RE
.PP
.B one message per file
.RS 5
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 \*(lq.\*(rq, all files that are not positive integers
.I must
be ignored by an
.BR MH \-compatible
implementation. However, implementations are free to indicate to the user
the existence of non-message files that are not prefixed with a \*(lq.\*(rq.
.PP
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
.I new
(e.g.,
.B mhpath
.IR new ).
New messages are
.I only
permitted to be added to a folder at the end of the message number range.
.PP
To add a new message to a folder, the recommended sequence is:
.IP \(bu 4
Create a temporary file in the desired folder.
.IP \(bu 4
Attempt to link the temporary file to the new message number.
.IP \(bu 4
If successful, remove the temporary file. If the link fails, increment the
message number and try again.
.RE
.B context
.RS 5
There is one context file. Its default location is in the
user's Path and its default name is
.IR context ,
but these can be overridden by the $MHCONTEXT environment variable.
.B context
has the following format:
.PP
.RS 5
.BI "Current-Folder: +" folder
.RE
.RS 5
.BI "atr-" sequence-path ": " "m[-n] [...]"
.RE
.PP
where
.I folder
is the directory name of the current folder. Lines beginning
with \*(lqatr\*(rq are used for private sequences.
.I sequence
is the name of the private sequence,
.I path
is the full path to the folder with the private sequence, and
.I m[-n]
is a message number or range of message numbers in the sequence.
.RE
.PP
.B sequences
.RS 5
There is one sequences file in each
.B nmh
folder. Its default name is
.IR \&.mh_sequences ,
but this can be overridden by the \*(lqmh\-sequences\*(rq profile entry.
.B sequences
has the following format:
.PP
.RS 5
.BI "sequence: " "m[-n] [...]"
.RE
.PP
showing the (possibly empty) message numbers and/or ranges of message
numbers in each sequence. The
.B cur
sequence has at most just a single message number, not a range.
.PP
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.
.PP
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
.B cur
sequence, which can refer to a nonexistent message.
.RE
.SS Locking
.B 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
.BR flist ,
.BR folder ,
.BR mark ,
.BR pick ,
and
.B rcvstore
should be used to query and update their contents. Any program
outside of
.B nmh
that accesses these files must be sure to lock them using the same
locking method as
.BR nmh .
The default data locking method is selected when
.B nmh
is configured and can be accessed as a string using
.BR "mhparam datalocking" .
By default, fcntl locking is used, but this may be overridden by
the
.B datalocking
profile entry.
.PP
A second, possibly different, locking method is used by
.IR inc (1)
when accessing the user's mail spool file or by
.B nmh
programs that open any mbox file. This locking method can be overridden
when
.B nmh
is configured, or in the
.B nmh
mts configuration file, and can be accessed as a string using
.BR "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
.B mail
program, if provided on the platform.
.SS Naming
.B nmh
folders can be given arbitrary names, with one exception:
folders should not be given all-numeric names. This
limitation results from
.B nmh
messages themselves being stored
in numerically named files -- allowing folders to be named
similarly would make
.B nmh
slower, and introduce usage ambiguities.
.SH FILES
.PD 0
.TP 20
<mh-dir>/context
The user's context.
.TP 20
$MHCONTEXT
Overrides the above context.
.TP 20
<folder>/.mh\-sequences
Public sequences for <folder>.
.SH "SEE ALSO"
.IR flist (1),
.IR folder (1),
.IR mail (1),
.IR mark (1),
.IR mhparam (1),
.IR mhpath (1),
.IR mh\-profile (5),
.IR mh\-sequence (5),
.IR mh\-tailor (5),
.IR pick (1),
.IR rcvstore (1)
|
