4 .TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
6 mhstore \- store contents of MIME messages into files
21 .RB [ \-auto " | " \-noauto ]
23 .IR always " | " auto " | " suffix " | " ask " | " never ]
28 .RB [ \-check " | " \-nocheck ]
35 command allows you to store the contents of a
36 collection of MIME (multi-media) messages into files or other
40 manipulates multi-media messages as specified in
41 RFC\-2045 thru RFC\-2049.
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
51 switches, you may limit the scope of
54 subparts (of a multipart content) and/or particular content types.
62 file as the source message, rather than a message from a folder.
63 If you specify this file as \*(lq-\*(rq, then
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
72 be in mail drop format (to convert a file in mail drop format to
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
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
89 switch will not prevent
90 the content from being acted upon.
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.
96 A list of commonly used contents is briefly reproduced here:
100 .ta \w'application 'u
104 multipart mixed, alternative, digest, parallel
105 message rfc822, partial, external-body
106 application octet-stream, postscript
113 A legal MIME message must contain a subtype specification.
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
121 a multipart content (of any subtype listed above) is always acted
122 upon. Further note that if the
124 switch is used, and it is
125 desirable to act on a message/external-body content, then the
127 switch must be used twice: once for message/external-body
128 and once for the content externally referenced.
129 .SS "Checking the Contents"
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
139 verify the integrity of the content.
140 .SS "Storing the Contents"
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
153 If this entry isn't present,
154 the current working directory is used.
158 switch is given, then
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
176 switch is not given (or is being ignored for security
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,
183 will look for an entry of
187 mhstore-store-<type>/<subtype>
190 to determine the formatting string. If this isn't found,
192 will look for an entry of the form:
198 to determine the formatting string.
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
205 If the formatting string consists solely of a \*(lq-\*(rq character,
206 then the content is sent to the standard output.
208 If the formatting string starts with a '|', then the display string
209 will represent a command for
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,
215 will change to the appropriate directory, and any
216 escapes (given below) in the display string will be expanded.
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. Note that if \*(lqnmh-storage\*(rq
224 is not an absolute path, it will be relative to the folder that
225 contains the message(s).
227 A command or pathname formatting string may contain the following
228 escapes. If the content isn't part of a multipart (of any subtype
229 listed above) content, the p-escapes are ignored.
234 %a Parameters from Content-type (only valid with command)
235 %m Insert message number
236 %P Insert part number with leading dot
237 %p Insert part number without leading dot
238 %t Insert content type
239 %s Insert content subtype
240 %% Insert character %
244 If no formatting string is found,
247 if the content is application/octet-stream with parameter
248 \*(lqtype=tar\*(rq. If so,
250 will choose an appropriate
251 filename. If the content is not application/octet-stream, then
253 will check to see if the content is a message. If
256 will use the value \*(lq+\*(rq. As a last resort,
258 will use the value \*(lq%m%P.%s\*(rq.
260 Example profile entries might be:
264 mhstore-store-text: %m%P.txt
265 mhstore-store-text: +inbox
266 mhstore-store-message/partial: +
267 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
268 mhstore-store-image/jpeg: %m%P.jpg
269 mhstore-store-application/PostScript: %m%P.ps
273 .SS "Overwriting Existing Files"
276 switch controls whether
278 should overwrite existing files. The allowed values for this switch
279 and corresponding behavior when
281 encounters an existing file are:
286 always Overwrite existing file (default)
287 auto Create new file of form name-n.extension
288 suffix Create new file of form name.extension.n
289 ask Prompt the user to specify whether or not to overwrite
291 never Do not overwrite existing file
300 is one beyond the existing file with the highest unused number,
301 starting from one, in the same form. If a filename does not have an
302 extension (following a '.'), then
306 create a new file of the form
316 will be the number of files that were requested but not stored.
320 if standard input is connected to a terminal,
321 the user is prompted to respond
326 to whether the file should be overwritten. The responses
327 can be abbreviated. If the user responds with
331 prompts the user for the name of the new file to be created. If it is
332 a relative path name (does not begin with '/'), then it is relative to
333 the current directory. If it is an absolute or relative path to a
334 directory that does not exist, the user will be prompted whether to
335 create the directory. If standard input is not connected to a
340 .SS "Reassembling Messages of Type message/partial"
342 is also able to reassemble messages that have been
343 split into multiple messages of type \*(lqmessage/partial\*(rq.
345 When asked to store a content containing a partial message,
347 will try to locate all of the portions and combine
348 them accordingly. The default is to store the combined parts as
349 a new message in the current folder, although this can be changed
350 using formatting strings as discussed above. Thus, if someone has
351 sent you a message in several parts (such as the output from
353 you can easily reassemble them all into a single
354 message in the following fashion:
359 msg part type/subtype size description
360 5 message/partial 47K part 1 of 4
361 6 message/partial 47K part 2 of 4
362 7 message/partial 47K part 3 of 4
363 8 message/partial 18K part 4 of 4
365 reassembling partials 5,6,7,8 to folder inbox as message 9
367 msg part type/subtype size description
368 9 application/octet-stream 118K
369 (extract with uncompress | tar xvpf -)
375 This will store exactly one message, containing the sum of the
376 parts. It doesn't matter whether the partials are specified in
379 will sort the partials, so that they
380 are combined in the correct order. But if
383 locate every partial necessary to reassemble the message, it will
385 .SS "External Access"
386 For contents of type message/external-body,
387 \fImhstore\fR supports these access-types:
400 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
402 will look for the \*(lqnmh-access-ftp\*(rq
406 nmh-access-ftp: myftp.sh
409 to determine the pathname of a program to perform the FTP retrieval.
410 This program is invoked with these arguments:
414 domain name of FTP-site
420 \*(lqascii\*(rq or \*(lqbinary\*(rq
424 The program should terminate with an exit status of zero if the
425 retrieval is successful, and a non-zero exit status otherwise.
426 .SS "The Content Cache"
429 encounters an external content containing a
430 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
431 depending on the caching behavior of
433 the content might be read from or written to a cache.
435 The caching behavior of
437 is controlled with the
441 switches, which define the policy for reading from,
442 and writing to, the cache, respectively. One of four policies may be
443 specified: \*(lqpublic\*(rq, indicating that
446 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
449 should make use of the user's private content cache;
450 \*(lqnever\*(rq, indicating that
452 should never make use of
453 caching; and, \*(lqask\*(rq, indicating that
457 There are two directories where contents may be cached: the profile entry
458 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
459 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
460 private contents. The former should be an absolute (rooted) directory
469 might be used if you didn't care that the cache got wiped after each
470 reboot of the system. The latter is interpreted relative to the user's
471 nmh directory, if not rooted, e.g.,
474 nmh-private-cache: .cache
477 (which is the default value).
478 .SS "User Environment"
479 Because the display environment in which
481 operates may vary for
484 will look for the environment variable
486 If present, this specifies the name of an additional
487 user profile which should be read. Hence, when a user logs in on a
488 particular machine, this environment variable should be set to
489 refer to a file containing definitions useful for that machine.
492 will attempt to consult one other additional
496 %etcdir%/mhn.defaults
499 which is created automatically during
506 .ta \w'%etcdir%/ExtraBigFileName 'u
507 ^$HOME/\&.mh\(ruprofile~^The user profile
508 ^$MHSTORE~^Additional profile entries
509 ^%etcdir%/mhn.defaults~^System default MIME profile entries
512 .SH "PROFILE COMPONENTS"
516 .ta \w'ExtraBigProfileName 'u
517 ^Path:~^To determine the user's nmh directory
518 ^Current\-Folder:~^To find the default current folder
519 ^nmh-access-ftp:~^Program to retrieve contents via FTP
520 ^nmh-cache~^Public directory to store cached external contents
521 ^nmh-private-cache~^Personal directory to store cached external contents
522 ^nmh-storage~^Directory to store contents
523 ^mhstore-store-<type>*~^Template for storing contents
527 mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
531 .RB ` +folder "' defaults to the current folder"
532 .RB ` msgs "' defaults to cur"
534 .RB ` \-clobber\ always '
536 .RB ` \-rcache\ ask '
537 .RB ` \-wcache\ ask '
540 If a folder is given, it will become the current folder. The last
541 message selected will become the current message.
544 Partial messages contained within a multipart content are not reassembled.
projects / mmh / blob