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

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