1 .TH MHSTORE %manext1% "March 21, 2013" "%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 to 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
160 will check if the message contains information indicating the filename
161 that should be used to store the content. This information should be
162 specified as the \*(lqfilename\*(rq attribute in the
163 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
164 attribute in the \*(lqContent-Type\*(rq header for the content you are
165 storing. For security reasons, this filename will be ignored if it
166 begins with the character '/', '.', '|', or '!', or if it contains the
167 character '%'. For the sake of security, this switch is not the
168 default, and it is recommended that you do NOT put the
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:
401 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
403 will look for the \*(lqnmh-access-ftp\*(rq
407 nmh-access-ftp: myftp.sh
410 to determine the pathname of a program to perform the FTP retrieval.
411 This program is invoked with these arguments:
415 domain name of FTP-site
421 \*(lqascii\*(rq or \*(lqbinary\*(rq
425 The program should terminate with an exit status of zero if the
426 retrieval is successful, and a non-zero exit status otherwise.
428 For the \*(lqurl\*(rq access types,
430 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
433 nmh-access-url: curl -l
436 to determine the program to use to perform the HTTP retrieval. This program
437 is invoked with one argument: the URL of the content to retrieve. The program
438 should write the content to standard out, and should terminate with a status of zero if the retrieval is successful and a non\-zero exit status otherwise.
440 .SS "The Content Cache"
443 encounters an external content containing a
444 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
445 depending on the caching behavior of
447 the content might be read from or written to a cache.
449 The caching behavior of
451 is controlled with the
455 switches, which define the policy for reading from,
456 and writing to, the cache, respectively. One of four policies may be
457 specified: \*(lqpublic\*(rq, indicating that
460 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
463 should make use of the user's private content cache;
464 \*(lqnever\*(rq, indicating that
466 should never make use of
467 caching; and, \*(lqask\*(rq, indicating that
471 There are two directories where contents may be cached: the profile entry
472 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
473 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
474 private contents. The former should be an absolute (rooted) directory
483 might be used if you didn't care that the cache got wiped after each
484 reboot of the system. The latter is interpreted relative to the user's
485 nmh directory, if not rooted, e.g.,
488 nmh-private-cache: .cache
491 (which is the default value).
492 .SS "User Environment"
493 Because the display environment in which
495 operates may vary for
498 will look for the environment variable
500 If present, this specifies the name of an additional
501 user profile which should be read. Hence, when a user logs in on a
502 particular machine, this environment variable should be set to
503 refer to a file containing definitions useful for that machine.
506 will attempt to consult one other additional
510 %etcdir%/mhn.defaults
513 which is created automatically during
518 looks for additional profile files in multiple locations: absolute
519 pathnames are accessed directly, tilde expansion is done on usernames,
520 and files are searched for in the user's
522 directory as specified in their profile. If not found there, the directory
523 .RI \*(lq %etcdir% \*(rq
528 .ta \w'%etcdir%/ExtraBigFileName 'u
529 ^$HOME/\&.mh\(ruprofile~^The user profile
530 ^$MHSTORE~^Additional profile entries
531 ^%etcdir%/mhn.defaults~^System default MIME profile entries
533 .SH "PROFILE COMPONENTS"
537 .ta \w'ExtraBigProfileName 'u
538 ^Path:~^To determine the user's nmh directory
539 ^Current\-Folder:~^To find the default current folder
540 ^nmh-access-ftp:~^Program to retrieve contents via FTP
541 ^nmh-access-url:~^Program to retrieve contents via HTTP
542 ^nmh-cache~^Public directory to store cached external contents
543 ^nmh-private-cache~^Personal directory to store cached external contents
544 ^nmh-storage~^Directory to store contents
545 ^mhstore-store-<type>*~^Template for storing contents
554 .RB ` +folder "' defaults to the current folder"
555 .RB ` msgs "' defaults to cur"
557 .RB ` \-clobber\ always '
559 .RB ` \-rcache\ ask '
560 .RB ` \-wcache\ ask '
562 If a folder is given, it will become the current folder. The last
563 message selected will become the current message.
565 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob