ae15292aacbd7b77df26506836c5bd1f5f0dbf68
[mmh] / man / mhstore.man
1 .\"
2 .\" %nmhwarning%
3 .\" $Id$
4 .\"
5 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 .SH NAME
7 mhstore \- store contents of MIME messages into files
8 .SH SYNOPSIS
9 .HP 5
10 .na
11 .B mhstore
12 .RI [ +folder ]
13 .RI [ msgs ]
14 .RB [ \-file
15 .IR file ]
16 .RB [ \-part
17 .IR number ]
18 \&...
19 .RB [ \-type
20 .IR content ]
21 \&...
22 .RB [ \-auto " | " \-noauto ]
23 .RB [ \-verbose " | " \-noverbose ]
24 .RB [ \-rcache
25 .IR policy ]
26 .RB [ \-wcache
27 .IR policy ]
28 .RB [ \-check " | " \-nocheck ]
29 .RB [ \-version ]
30 .RB [ \-help ]
31 .ad
32 .SH DESCRIPTION
33 The
34 .B mhstore
35 command allows you to store the contents of a
36 collection of MIME (multi-media) messages into files or other
37 messages.
38 .PP
39 .B mhstore
40 manipulates multi-media messages as specified in
41 RFC\-2045 thru RFC\-2049.
42 .PP
43 By default,
44 .B mhstore
45 will store all the parts of each message.
46 Each part will be store in a separate file.  The header fields of
47 the message are not stored.  By using the
48 .B \-part
49 and
50 .B \-type
51 switches, you may limit the scope of
52 .B mhstore
53 to particular
54 subparts (of a multipart content) and/or particular content types.
55 .PP
56 The option
57 .B \-file
58 .I file
59 directs
60 .B mhstore
61 to use the specified
62 file as the source message, rather than a message from a folder.
63 If you specify this file as \*(lq-\*(rq, then
64 .B mhstore
65 will
66 accept the source message on the standard input.  Note that the
67 file, or input from standard input should be a validly formatted
68 message, just like any other
69 .B nmh
70 message.  It should
71 .B NOT
72 be in mail drop format (to convert a file in mail drop format to
73 a folder of
74 .B nmh
75 messages, see
76 .BR inc (1)).
77 .PP
78 A part specification consists of a series of numbers separated by
79 dots.  For example, in a multipart content containing three parts,
80 these would be named as 1, 2, and 3, respectively.  If part 2 was
81 also a multipart content containing two parts, these would be named
82 as 2.1 and 2.2, respectively.  Note that the
83 .B \-part
84 switch is
85 effective for only messages containing a multipart content.  If a
86 message has some other kind of content, or if the part is itself
87 another multipart content, the
88 .B \-part
89 switch will not prevent
90 the content from being acted upon.
91 .PP
92 A content specification consists of a content type and a subtype.
93 The initial list of \*(lqstandard\*(rq content types and subtypes
94 can be found in RFC\-2046.
95 .PP
96 A list of commonly used contents is briefly reproduced here:
97 .PP
98 .RS 5
99 .nf
100 .ta \w'application  'u
101 Type    Subtypes
102 ----    --------
103 text    plain, enriched
104 multipart       mixed, alternative, digest, parallel
105 message rfc822, partial, external-body
106 application     octet-stream, postscript
107 image   jpeg, gif, png
108 audio   basic
109 video   mpeg
110 .fi
111 .RE
112 .PP
113 A legal MIME message must contain a subtype specification.
114 .PP
115 To specify a content, regardless of its subtype, just use the name
116 of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
117 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
118 Note that regardless of the values given to the
119 .B \-type
120 switch,
121 a multipart content (of any subtype listed above) is always acted
122 upon.  Further note that if the
123 .B \-type
124 switch is used, and it is
125 desirable to act on a message/external-body content, then the
126 .B \-type
127 switch must be used twice: once for message/external-body
128 and once for the content externally referenced.
129 .SS "Checking the Contents"
130 The
131 .B \-check
132 switch tells
133 .B mhstore
134 to check each content for
135 an integrity checksum.  If a content has such a checksum (specified
136 as a Content-MD5 header field), then
137 .B mhstore
138 will attempt to
139 verify the integrity of the content.
140 .SS "Storing the Contents"
141 The
142 .B mhstore
143 will store the contents of the named messages in
144 \*(lqnative\*(rq (decoded) format.  Two things must be determined:
145 the directory to store the content, and the filenames.  Files are
146 written in the directory given by the \*(lqnmh-storage\*(rq profile
147 entry, e.g.,
148 .PP
149 .RS 5
150 nmh-storage: /tmp
151 .RE
152 .PP
153 If this entry isn't present,
154 the current working directory is used.
155 .PP
156 If the
157 .B \-auto
158 switch is given, then
159 .B mhstore
160 will check if
161 the message contains information indicating the filename that should
162 be used to store the content.  This information should be specified
163 as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
164 for the content you are storing.  For security reasons, this filename
165 will be ignored if it begins with the character '/', '.', '|', or
166 '!', or if it contains the character '%'.  For the sake of security,
167 this switch is not the default, and it is recommended that you do
168 NOT put the
169 .B \-auto
170 switch in your
171 .I \&.mh\(ruprofile
172 file.
173 .PP
174 If the
175 .B \-auto
176 switch is not given (or is being ignored for security
177 reasons) then
178 .B mhstore
179 will look in the user's profile for a
180 \*(lqformatting string\*(rq to determine how the different contents
181 should be stored.  First,
182 .B mhstore
183 will look for an entry of
184 the form:
185 .PP
186 .RS 5
187 mhstore-store-<type>/<subtype>
188 .RE
189 .PP
190 to determine the formatting string.  If this isn't found,
191 .B mhstore
192 will look for an entry of the form:
193 .PP
194 .RS 5
195 mhstore-store-<type>
196 .RE
197 .PP
198 to determine the formatting string.
199 .PP
200 If the formatting string starts with a \*(lq+\*(rq character, then
201 content is stored in the named folder.  A formatting string consisting
202 solely of a \*(lq+\*(rq character is interpreted to be the current
203 folder.
204 .PP
205 If the formatting string consists solely of a \*(lq-\*(rq character,
206 then the content is sent to the standard output.
207 .PP
208 If the formatting string starts with a '|', then the display string
209 will represent a command for
210 .B mhstore
211 to execute which should
212 ultimately store the content.  The content will be passed to the
213 standard input of the command.  Before the command is executed,
214 .B mhstore
215 will change to the appropriate directory, and any
216 escapes (given below) in the display string will be expanded.
217 .PP
218 Otherwise the formatting string will represent a pathname in which
219 to store the content.  If the formatting string starts with a '/',
220 then the content will be stored in the full path given, else the
221 file name will be relative to the value of \*(lqnmh-storage\*(rq or
222 the current working directory.  Any escapes (given below) will be
223 expanded, except for the a-escape.
224 .PP
225 A command or pathname formatting string may contain the following
226 escapes.  If the content isn't part of a multipart (of any subtype
227 listed above) content, the p-escapes are ignored.
228 .PP
229 .RS 5
230 .nf
231 .ta \w'%P  'u
232 %a      Parameters from Content-type  (only valid with command)
233 %m      Insert message number
234 %P      Insert part number with leading dot
235 %p      Insert part number without leading dot
236 %t      Insert content type
237 %s      Insert content subtype
238 %%      Insert character %
239 .fi
240 .RE
241 .PP
242 If no formatting string is found,
243 .B mhstore
244 will check to see
245 if the content is application/octet-stream with parameter
246 \*(lqtype=tar\*(rq.  If so,
247 .B mhstore
248 will choose an appropriate
249 filename.  If the content is not application/octet-stream, then
250 .B mhstore
251 will check to see if the content is a message.  If
252 so,
253 .B mhstore
254 will use the value \*(lq+\*(rq.  As a last resort,
255 .B mhstore
256 will use the value \*(lq%m%P.%s\*(rq.
257 .PP
258 Example profile entries might be:
259 .PP
260 .RS 5
261 .nf
262 mhstore-store-text: %m%P.txt
263 mhstore-store-text: +inbox
264 mhstore-store-message/partial: +
265 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
266 mhstore-store-image/jpeg: %m%P.jpg
267 mhstore-store-application/PostScript: %m%P.ps
268 .fi
269 .RE
270 .PP
271 .SS "Reassembling Messages of Type message/partial"
272 .B mhstore
273 is also able to reassemble messages that have been
274 split into multiple messages of type \*(lqmessage/partial\*(rq.
275 .PP
276 When asked to store a content containing a partial message,
277 .B mhstore
278 will try to locate all of the portions and combine
279 them accordingly.  The default is to store the combined parts as
280 a new message in the current folder, although this can be changed
281 using formatting strings as discussed above.  Thus, if someone has
282 sent you a message in several parts (such as the output from
283 .BR sendfiles ),
284 you can easily reassemble them all into a single
285 message in the following fashion:
286 .PP
287 .RS 5
288 .nf
289 % mhlist 5-8
290  msg part  type/subtype             size description
291    5       message/partial           47K part 1 of 4
292    6       message/partial           47K part 2 of 4
293    7       message/partial           47K part 3 of 4
294    8       message/partial           18K part 4 of 4
295 % mhstore 5-8
296 reassembling partials 5,6,7,8 to folder inbox as message 9
297 % mhlist -verbose 9
298  msg part  type/subtype             size description
299    9       application/octet-stream 118K
300              (extract with uncompress | tar xvpf -)
301              type=tar
302              conversions=compress
303 .fi
304 .RE
305 .PP
306 This will store exactly one message, containing the sum of the
307 parts.  It doesn't matter whether the partials are specified in
308 order, since
309 .B mhstore
310 will sort the partials, so that they
311 are combined in the correct order.  But if
312 .B mhstore
313 can not
314 locate every partial necessary to reassemble the message, it will
315 not store anything.
316 .SS "External Access"
317 For contents of type message/external-body,
318 \fImhstore\fR supports these access-types:
319 .PP
320 .IP \(bu 4
321 afs
322 .IP \(bu 4
323 anon-ftp
324 .IP \(bu 4
325 ftp
326 .IP \(bu 4
327 local-file
328 .IP \(bu 4
329 mail-server
330 .PP
331 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
332 .B mhstore
333 will look for the \*(lqnmh-access-ftp\*(rq
334 profile entry, e.g.,
335 .PP
336 .RS 5
337 nmh-access-ftp: myftp.sh
338 .RE
339 .PP
340 to determine the pathname of a program to perform the FTP retrieval.
341 This program is invoked with these arguments:
342 .PP
343 .RS 5
344 .nf
345 domain name of FTP-site
346 username
347 password
348 remote directory
349 remote filename
350 local filename
351 \*(lqascii\*(rq or \*(lqbinary\*(rq
352 .fi
353 .RE
354 .PP
355 The program should terminate with an exit status of zero if the
356 retrieval is successful, and a non-zero exit status otherwise.
357 .PP
358 If this entry is not provided, then
359 .B mhstore
360 will use a simple
361 built-in FTP client to perform the retrieval.
362 .SS "The Content Cache"
363 When
364 .B mhstore
365 encounters an external content containing a
366 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
367 depending on the caching behavior of
368 .BR mhstore ,
369 the content might be read from or written to a cache.
370 .PP
371 The caching behavior of
372 .B mhstore
373 is controlled with the
374 .B \-rcache
375 and
376 .B \-wcache
377 switches, which define the policy for reading from,
378 and writing to, the cache, respectively.  One of four policies may be
379 specified: \*(lqpublic\*(rq, indicating that
380 .B mhstore
381 should make use
382 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
383 that
384 .B mhstore
385 should make use of the user's private content cache;
386 \*(lqnever\*(rq, indicating that
387 .B mhstore
388 should never make use of
389 caching; and, \*(lqask\*(rq, indicating that
390 .B mhstore
391 should ask the user.
392 .PP
393 There are two directories where contents may be cached: the profile entry
394 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
395 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
396 private contents.  The former should be an absolute (rooted) directory
397 name.
398 .PP
399 For example,
400 .PP
401 .RS 5
402 nmh-cache: /tmp
403 .RE
404 .PP
405 might be used if you didn't care that the cache got wiped after each
406 reboot of the system.  The latter is interpreted relative to the user's
407 nmh directory, if not rooted, e.g.,
408 .PP
409 .RS 5
410 nmh-private-cache: .cache
411 .RE
412 .PP
413 (which is the default value).
414 .SS "User Environment"
415 Because the display environment in which
416 .B mhstore
417 operates may vary for
418 different machines,
419 .B mhstore
420 will look for the environment variable
421 .BE $MHSTORE .
422 If present, this specifies the name of an additional
423 user profile which should be read.  Hence, when a user logs in on a
424 particular machine, this environment variable should be set to
425 refer to a file containing definitions useful for that machine.
426 Finally,
427 .B mhstore
428 will attempt to consult one other additional
429 user profile, e.g.,
430 .PP
431 .RS 5
432 %etcdir%/mhn.defaults
433 .RE
434 .PP
435 which is created automatically during
436 .B nmh
437 installation.
438
439 .SH FILES
440 .fc ^ ~
441 .nf
442 .ta \w'%etcdir%/ExtraBigFileName  'u
443 ^$HOME/\&.mh\(ruprofile~^The user profile
444 ^$MHSTORE~^Additional profile entries
445 ^%etcdir%/mhn.defaults~^System default MIME profile entries
446 .fi
447
448 .SH "PROFILE COMPONENTS"
449 .fc ^ ~
450 .nf
451 .ta 2.4i
452 .ta \w'ExtraBigProfileName  'u
453 ^Path:~^To determine the user's nmh directory
454 ^Current\-Folder:~^To find the default current folder
455 ^nmh-access-ftp:~^Program to retrieve contents via FTP
456 ^nmh-cache~^Public directory to store cached external contents
457 ^nmh-private-cache~^Personal directory to store cached external contents
458 ^nmh-storage~^Directory to store contents
459 ^mhstore-store-<type>*~^Template for storing contents
460 .fi
461
462 .SH "SEE ALSO"
463 mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
464
465 .SH DEFAULTS
466 .nf
467 .RB ` +folder "' defaults to the current folder"
468 .RB ` msgs "' defaults to cur"
469 .RB ` \-noauto '
470 .RB ` \-nocheck '
471 .RB ` \-rcache ask '
472 .RB ` \-wcache ask '
473 .RB ` \-noverbose '
474
475 .SH CONTEXT
476 If a folder is given, it will become the current folder.  The last
477 message selected will become the current message.
478
479 .SH BUGS
480 Partial messages contained within a multipart content are not reassembled.