diplodocus.org Git - nmh/blob - man/mh-folders.man

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