X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/c0d6a31061bba17b20e2d5a317f244fb63664eec..63621a81d16ab743de6b57d47578a9a2c670ad22:/man/mh-folders.man diff --git a/man/mh-folders.man b/man/mh-folders.man index 5e29d43c..a3ed3f09 100644 --- a/man/mh-folders.man +++ b/man/mh-folders.man @@ -1,9 +1,9 @@ -.TH MH-MAIL %manext5% "March 3, 2013" "%nmhversion%" -.\" +.TH MH-FOLDERS %manext5% 2016-02-25 "%nmhversion%" +. .\" %nmhwarning% -.\" +. .SH NAME -mh-folders \- specification of storage format used by nmh message system +mh-folders \- storage format used by nmh message system .SH DESCRIPTION .B nmh stores messages in the files and directories of the host filesystem @@ -11,29 +11,48 @@ according to the following rules: .PP .B one folder per directory .RS 5 -A +An .B nmh -folder corresponds to directory. There are no limits on folder +folder corresponds to a directory. There are no limits on folder names beyond those of the host filesystem. -.I Is that right? .RE .PP .B one message per file .RS 5 -The file name is a positive integer. The filename for a new -message is one greater than the highest numbered message in -the folder; its full path can be shown by -.B mh-path -.IR new . +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 default name is +user's Path and its default name is .IR context , -but those can be overridden with the $MHCONTEXT environment -variable. +but these can be overridden by the $MHCONTEXT environment variable. .B context has the following format: .PP @@ -59,10 +78,10 @@ is a message number or range of message numbers in the sequence. .B sequences .RS 5 There is one sequences file in each -.B .nmh +.B nmh folder. Its default name is -.IR \&.mh\(rusequences , -but that can be overridden with the \*(lqmh\-sequences\*(rq profile entry. +.IR \&.mh_sequences , +but this can be overridden by the \*(lqmh\-sequences\*(rq profile entry. .B sequences has the following format: .PP @@ -70,35 +89,96 @@ has the following format: .BI "sequence: " "m[-n] [...]" .RE .PP -showing the message numbers and/or ranges of message numbers in -each sequence. -.RE +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. Any program outside of +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. The locking method is selected when +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 -is configured. 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 +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. -.I Should we add a lockmethod component to mhparam so users can easily detect it? +.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 -.fc ^ ~ -.nf -.ta \w'%etcdir%/ExtraBigFileName 'u -^/context~^The user context -^or $MHCONTEXT~^Rather than the standard context -^/\&.mh\(rusequences~^Public sequences for -.fi +.PD 0 +.TP 20 +/context +The user's context. +.TP 20 +$MHCONTEXT +Overrides the above context. +.TP 20 +/.mh\-sequences +Public sequences for . .SH "SEE ALSO" -.I +.IR flist (1), +.IR folder (1), .IR mail (1), -.IR mh\-path (1), +.IR mark (1), +.IR mhparam (1), +.IR mhpath (1), .IR mh\-profile (5), -.IR mh\-sequence (5) +.IR mh\-sequence (5), +.IR mh\-tailor (5), +.IR pick (1), +.IR rcvstore (1)