4 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhstore \- store contents of MIME messages into files
21 .RB [ \-auto " | " \-noauto ]
32 command allows you to store the contents of a
33 collection of MIME (multi-media) messages into files or other
37 manipulates multi-media messages as specified in
38 RFC\-2045 thru RFC\-2049.
42 will store all the parts of each message.
43 Each part will be store in a separate file. The header fields of
44 the message are not stored. By using the
48 switches, you may limit the scope of
51 subparts (of a multipart content) and/or particular content types.
59 file as the source message, rather than a message from a folder.
60 If you specify this file as \*(lq-\*(rq, then
63 accept the source message on the standard input. Note that the
64 file, or input from standard input should be a validly formatted
65 message, just like any other
69 be in mail drop format (to convert a file in mail drop format to
75 A part specification consists of a series of numbers separated by
76 dots. For example, in a multipart content containing three parts,
77 these would be named as 1, 2, and 3, respectively. If part 2 was
78 also a multipart content containing two parts, these would be named
79 as 2.1 and 2.2, respectively. Note that the
82 effective for only messages containing a multipart content. If a
83 message has some other kind of content, or if the part is itself
84 another multipart content, the
86 switch will not prevent
87 the content from being acted upon.
89 A content specification consists of a content type and a subtype.
90 The initial list of \*(lqstandard\*(rq content types and subtypes
91 can be found in RFC\-2046.
93 A list of commonly used contents is briefly reproduced here:
101 multipart mixed, alternative, digest, parallel
102 message rfc822, partial, external-body
103 application octet-stream, postscript
110 A legal MIME message must contain a subtype specification.
112 To specify a content, regardless of its subtype, just use the name
113 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
114 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
115 Note that regardless of the values given to the
118 a multipart content (of any subtype listed above) is always acted
119 upon. Further note that if the
121 switch is used, and it is
122 desirable to act on a message/external-body content, then the
124 switch must be used twice: once for message/external-body
125 and once for the content externally referenced.
126 .SS "Storing the Contents"
129 will store the contents of the named messages in
130 \*(lqnative\*(rq (decoded) format. Two things must be determined:
131 the directory to store the content, and the filenames. Files are
132 written in the directory given by the \*(lqnmh-storage\*(rq profile
139 If this entry isn't present,
140 the current working directory is used.
144 switch is given, then
147 the message contains information indicating the filename that should
148 be used to store the content. This information should be specified
149 as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
150 for the content you are storing. For security reasons, this filename
151 will be ignored if it begins with the character '/', '.', '|', or '!',
152 or if it contains the character '%'. For the sake of security,
153 this switch is not the default, and it is recommended that you do
162 switch is not given (or is being ignored for security
165 will look in the user's profile for a
166 \*(lqformatting string\*(rq to determine how the different contents
167 should be stored. First,
169 will look for an entry of
173 mhstore-store-<type>/<subtype>
176 to determine the formatting string. If this isn't found,
178 will look for an entry of the form:
184 to determine the formatting string.
186 If the formatting string starts with a \*(lq+\*(rq character, then
187 content is stored in the named folder. A formatting string consisting
188 solely of a \*(lq+\*(rq character is interpreted to be the current
191 If the formatting string consists solely of a \*(lq-\*(rq character,
192 then the content is sent to the standard output.
194 If the formatting string starts with a '|', then the display string
195 will represent a command for
197 to execute which should
198 ultimately store the content. The content will be passed to the
199 standard input of the command. Before the command is executed,
201 will change to the appropriate directory, and any
202 escapes (given below) in the display string will be expanded.
204 Otherwise the formatting string will represent a pathname in which
205 to store the content. If the formatting string starts with a '/',
206 then the content will be stored in the full path given, else the
207 file name will be relative to the value of \*(lqnmh-storage\*(rq or
208 the current working directory. Any escapes (given below) will be
209 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
210 is not an absolute path, it will be relative to the folder that
211 contains the message(s).
213 A command or pathname formatting string may contain the following
214 escapes. If the content isn't part of a multipart (of any subtype
215 listed above) content, the p-escapes are ignored.
220 %a Parameters from Content-type (only valid with command)
221 %m Insert message number
222 %P Insert part number with leading dot
223 %p Insert part number without leading dot
224 %t Insert content type
225 %s Insert content subtype
226 %% Insert character %
230 If no formatting string is found,
233 if the content is application/octet-stream with parameter
234 \*(lqtype=tar\*(rq. If so,
236 will choose an appropriate
237 filename. If the content is not application/octet-stream, then
239 will check to see if the content is a message. If
242 will use the value \*(lq+\*(rq. As a last resort,
244 will use the value \*(lq%m%P.%s\*(rq.
246 Example profile entries might be:
250 mhstore-store-text: %m%P.txt
251 mhstore-store-text: +inbox
252 mhstore-store-message/partial: +
253 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
254 mhstore-store-image/jpeg: %m%P.jpg
255 mhstore-store-application/PostScript: %m%P.ps
259 .SS "Reassembling Messages of Type message/partial"
261 is also able to reassemble messages that have been
262 split into multiple messages of type \*(lqmessage/partial\*(rq.
264 When asked to store a content containing a partial message,
266 will try to locate all of the portions and combine
267 them accordingly. The default is to store the combined parts as
268 a new message in the current folder, although this can be changed
269 using formatting strings as discussed above. Thus, if someone has
270 sent you a message in several parts (such as the output from
272 you can easily reassemble them all into a single
273 message in the following fashion:
278 msg part type/subtype size description
279 5 message/partial 47K part 1 of 4
280 6 message/partial 47K part 2 of 4
281 7 message/partial 47K part 3 of 4
282 8 message/partial 18K part 4 of 4
284 reassembling partials 5,6,7,8 to folder inbox as message 9
286 msg part type/subtype size description
287 9 application/octet-stream 118K
288 (extract with uncompress | tar xvpf -)
294 This will store exactly one message, containing the sum of the
295 parts. It doesn't matter whether the partials are specified in
298 will sort the partials, so that they
299 are combined in the correct order. But if
302 locate every partial necessary to reassemble the message, it will
310 will automatically do the extraction for you:
315 msg part type/subtype size description
316 5 message/partial 47K part 1 of 4
317 6 message/partial 47K part 2 of 4
318 7 message/partial 47K part 3 of 4
319 8 message/partial 18K part 4 of 4
321 reassembling partials 5,6,7,8 to folder inbox as message 9
323 msg part type/subtype size description
324 9 application/octet-stream 118K
325 (extract with uncompress | tar xvpf -)
329 -- tar listing appears here as files are extracted
335 listing is generated, the files are extracted.
336 A prudent user will never put
339 The correct procedure is to first use
341 to find out what will be extracted. Then
345 to perform the extraction.
346 .SS "External Access"
347 For contents of type message/external-body,
348 \fImhstore\fR supports these access-types:
361 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
363 will look for the \*(lqnmh-access-ftp\*(rq
367 nmh-access-ftp: myftp.sh
370 to determine the pathname of a program to perform the FTP retrieval.
371 This program is invoked with these arguments:
375 domain name of FTP-site
381 \*(lqascii\*(rq or \*(lqbinary\*(rq
385 The program should terminate with an exit status of zero if the
386 retrieval is successful, and a non-zero exit status otherwise.
387 .SS "The Content Cache"
390 encounters an external content containing a
391 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
392 depending on the caching behavior of
394 the content might be read from or written to a cache.
396 The caching behavior of
398 is controlled with the
402 switches, which define the policy for reading from,
403 and writing to, the cache, respectively. One of four policies may be
404 specified: \*(lqpublic\*(rq, indicating that
407 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
410 should make use of the user's private content cache;
411 \*(lqnever\*(rq, indicating that
413 should never make use of
414 caching; and, \*(lqask\*(rq, indicating that
418 There are two directories where contents may be cached: the profile entry
419 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
420 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
421 private contents. The former should be an absolute (rooted) directory
430 might be used if you didn't care that the cache got wiped after each
431 reboot of the system. The private chace is interpreted relative to the user's
432 mail storage, if not rooted, e.g.,
435 nmh-private-cache: .cache
438 (which is the default value).
439 .SS "User Environment"
440 Because the display environment in which
442 operates may vary for
445 will look for the environment variable
447 If present, this specifies the name of an additional
448 user profile which should be read. Hence, when a user logs in on a
449 particular machine, this environment variable should be set to
450 refer to a file containing definitions useful for that machine.
453 will attempt to consult one other additional
457 %etcdir%/mhn.defaults
460 which is created automatically during
467 .ta \w'%etcdir%/ExtraBigFileName 'u
468 ^$HOME/.mmh/profile~^The user profile
469 ^$MHSTORE~^Additional profile entries
470 ^%etcdir%/mhn.defaults~^System default MIME profile entries
473 .SH "PROFILE COMPONENTS"
477 .ta \w'ExtraBigProfileName 'u
478 ^Path:~^To determine the user's mail storage
479 ^Current\-Folder:~^To find the default current folder
480 ^nmh-access-ftp:~^Program to retrieve contents via FTP
481 ^nmh-cache~^Public directory to store cached external contents
482 ^nmh-private-cache~^Personal directory to store cached external contents
483 ^nmh-storage~^Directory to store contents
484 ^mhstore-store-<type>*~^Template for storing contents
488 mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
492 .RB ` +folder "' defaults to the current folder"
493 .RB ` msgs "' defaults to cur"
495 .RB ` \-rcache \ ask'
496 .RB ` \-wcache \ ask'
499 If a folder is given, it will become the current folder. The last
500 message selected will become the current message.
503 Partial messages contained within a multipart content are not reassembled.