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 the lowest unused number, starting from one, in the same form. If
301 a filename does not have an extension (following a '.'), then
305 create a new file of the form
315 will be the number of files that were requested but not stored.
319 if standard input is connected to a terminal,
320 the user is prompted to respond
325 to whether the file should be overwritten. The responses
326 can be abbreviated. If the user responds with
330 prompts the user for the name of the new file to be created. If it is
331 a relative path name (does not begin with '/'), then it is relative to
332 the current directory. If it is an absolute or relative path to a
333 directory that does not exist, the user will be prompted whether to
334 create the directory. If standard input is not connected to a
339 .SS "Reassembling Messages of Type message/partial"
341 is also able to reassemble messages that have been
342 split into multiple messages of type \*(lqmessage/partial\*(rq.
344 When asked to store a content containing a partial message,
346 will try to locate all of the portions and combine
347 them accordingly. The default is to store the combined parts as
348 a new message in the current folder, although this can be changed
349 using formatting strings as discussed above. Thus, if someone has
350 sent you a message in several parts (such as the output from
352 you can easily reassemble them all into a single
353 message in the following fashion:
358 msg part type/subtype size description
359 5 message/partial 47K part 1 of 4
360 6 message/partial 47K part 2 of 4
361 7 message/partial 47K part 3 of 4
362 8 message/partial 18K part 4 of 4
364 reassembling partials 5,6,7,8 to folder inbox as message 9
366 msg part type/subtype size description
367 9 application/octet-stream 118K
368 (extract with uncompress | tar xvpf -)
374 This will store exactly one message, containing the sum of the
375 parts. It doesn't matter whether the partials are specified in
378 will sort the partials, so that they
379 are combined in the correct order. But if
382 locate every partial necessary to reassemble the message, it will
384 .SS "External Access"
385 For contents of type message/external-body,
386 \fImhstore\fR supports these access-types:
399 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
401 will look for the \*(lqnmh-access-ftp\*(rq
405 nmh-access-ftp: myftp.sh
408 to determine the pathname of a program to perform the FTP retrieval.
409 This program is invoked with these arguments:
413 domain name of FTP-site
419 \*(lqascii\*(rq or \*(lqbinary\*(rq
423 The program should terminate with an exit status of zero if the
424 retrieval is successful, and a non-zero exit status otherwise.
425 .SS "The Content Cache"
428 encounters an external content containing a
429 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
430 depending on the caching behavior of
432 the content might be read from or written to a cache.
434 The caching behavior of
436 is controlled with the
440 switches, which define the policy for reading from,
441 and writing to, the cache, respectively. One of four policies may be
442 specified: \*(lqpublic\*(rq, indicating that
445 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
448 should make use of the user's private content cache;
449 \*(lqnever\*(rq, indicating that
451 should never make use of
452 caching; and, \*(lqask\*(rq, indicating that
456 There are two directories where contents may be cached: the profile entry
457 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
458 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
459 private contents. The former should be an absolute (rooted) directory
468 might be used if you didn't care that the cache got wiped after each
469 reboot of the system. The latter is interpreted relative to the user's
470 nmh directory, if not rooted, e.g.,
473 nmh-private-cache: .cache
476 (which is the default value).
477 .SS "User Environment"
478 Because the display environment in which
480 operates may vary for
483 will look for the environment variable
485 If present, this specifies the name of an additional
486 user profile which should be read. Hence, when a user logs in on a
487 particular machine, this environment variable should be set to
488 refer to a file containing definitions useful for that machine.
491 will attempt to consult one other additional
495 %etcdir%/mhn.defaults
498 which is created automatically during
505 .ta \w'%etcdir%/ExtraBigFileName 'u
506 ^$HOME/\&.mh\(ruprofile~^The user profile
507 ^$MHSTORE~^Additional profile entries
508 ^%etcdir%/mhn.defaults~^System default MIME profile entries
511 .SH "PROFILE COMPONENTS"
515 .ta \w'ExtraBigProfileName 'u
516 ^Path:~^To determine the user's nmh directory
517 ^Current\-Folder:~^To find the default current folder
518 ^nmh-access-ftp:~^Program to retrieve contents via FTP
519 ^nmh-cache~^Public directory to store cached external contents
520 ^nmh-private-cache~^Personal directory to store cached external contents
521 ^nmh-storage~^Directory to store contents
522 ^mhstore-store-<type>*~^Template for storing contents
526 mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
530 .RB ` +folder "' defaults to the current folder"
531 .RB ` msgs "' defaults to cur"
533 .RB ` \-clobber\ always '
535 .RB ` \-rcache\ ask '
536 .RB ` \-wcache\ ask '
539 If a folder is given, it will become the current folder. The last
540 message selected will become the current message.
543 Partial messages contained within a multipart content are not reassembled.
projects / mmh / blob