1 .TH MHSTORE %manext1% "March 21, 2013" "%nmhversion%"
6 mhstore \- store contents of MIME messages into files
23 .RB [ \-auto " | " \-noauto ]
25 .IR always " | " auto " | " suffix " | " ask " | " never ]
30 .RB [ \-check " | " \-nocheck ]
37 command allows you to store the contents of a
38 collection of MIME (multi-media) messages into files or other
42 manipulates multi-media messages as specified in
47 will store all the parts of each message.
48 Each part will be store in a separate file. The header fields of
49 the message are not stored. By using the
53 switches, you may limit the scope of
56 subparts (of a multipart content) and/or particular content types.
64 file as the source message, rather than a message from a folder.
65 If you specify this file as \*(lq-\*(rq, then
68 accept the source message on the standard input. Note that the
69 file, or input from standard input should be a validly formatted
70 message, just like any other
74 be in mail drop format (to convert a file in mail drop format to
80 A part specification consists of a series of numbers separated by
81 dots. For example, in a multipart content containing three parts,
82 these would be named as 1, 2, and 3, respectively. If part 2 was
83 also a multipart content containing two parts, these would be named
84 as 2.1 and 2.2, respectively. Note that the
87 effective for only messages containing a multipart content. If a
88 message has some other kind of content, or if the part is itself
89 another multipart content, the
91 switch will not prevent
92 the content from being acted upon.
94 A content specification consists of a content type and a subtype.
95 The initial list of \*(lqstandard\*(rq content types and subtypes
96 can be found in RFC 2046.
98 A list of commonly used contents is briefly reproduced here:
102 .ta \w'application 'u
106 multipart mixed, alternative, digest, parallel
107 message rfc822, partial, external-body
108 application octet-stream, postscript
115 A legal MIME message must contain a subtype specification.
117 To specify a content, regardless of its subtype, just use the name
118 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
119 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
120 Note that regardless of the values given to the
123 a multipart content (of any subtype listed above) is always acted
124 upon. Further note that if the
126 switch is used, and it is
127 desirable to act on a message/external-body content, then the
129 switch must be used twice: once for message/external-body
130 and once for the content externally referenced.
131 .SS "Checking the Contents"
136 to check each content for
137 an integrity checksum. If a content has such a checksum (specified
138 as a Content-MD5 header field), then
141 verify the integrity of the content.
142 .SS "Storing the Contents"
145 will store the contents of the named messages in
146 \*(lqnative\*(rq (decoded) format. Two things must be determined:
147 the directory to store the content, and the filenames. Files are
148 written in the directory given by the \*(lqnmh-storage\*(rq profile
155 If this entry isn't present,
156 the current working directory is used.
160 switch is given, its argument is used for the filename to store all
161 of the content, with \*(lq-\*(rq indicating standard output. If the
163 switch is given, then
165 will check if the message contains information indicating the filename
166 that should be used to store the content. This information should be
167 specified as the \*(lqfilename\*(rq attribute in the
168 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
169 attribute in the \*(lqContent-Type\*(rq header for the content you are
170 storing. For security reasons, this filename will be ignored if it
171 begins with the character '/', '.', '|', or '!', or if it contains the
172 character '%'. For the sake of security, this switch is not the
173 default, and it is recommended that you do NOT put the
181 switch is not given (or is being ignored for security
184 will look in the user's profile for a
185 \*(lqformatting string\*(rq to determine how the different contents
186 should be stored. First,
188 will look for an entry of
192 mhstore-store-<type>/<subtype>
195 to determine the formatting string. If this isn't found,
197 will look for an entry of the form:
203 to determine the formatting string.
205 If the formatting string starts with a \*(lq+\*(rq character, then
206 content is stored in the named folder. A formatting string consisting
207 solely of a \*(lq+\*(rq character is interpreted to be the current
210 If the formatting string consists solely of a \*(lq-\*(rq character,
211 then the content is sent to the standard output.
213 If the formatting string starts with a '|', then the display string
214 will represent a command for
216 to execute which should
217 ultimately store the content. The content will be passed to the
218 standard input of the command. Before the command is executed,
220 will change to the appropriate directory, and any
221 escapes (given below) in the display string will be expanded.
223 Otherwise the formatting string will represent a pathname in which
224 to store the content. If the formatting string starts with a '/',
225 then the content will be stored in the full path given, else the
226 file name will be relative to the value of \*(lqnmh-storage\*(rq or
227 the current working directory. Any escapes (given below) will be
228 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
229 is not an absolute path, it will be relative to the folder that
230 contains the message(s).
232 A command or pathname formatting string may contain the following
233 escapes. If the content isn't part of a multipart (of any subtype
234 listed above) content, the p-escapes are ignored.
239 %a Parameters from Content-type (only valid with command)
240 %m Insert message number
241 %P Insert part number with leading dot
242 %p Insert part number without leading dot
243 %t Insert content type
244 %s Insert content subtype
245 %% Insert character %
249 If no formatting string is found,
252 if the content is application/octet-stream with parameter
253 \*(lqtype=tar\*(rq. If so,
255 will choose an appropriate
256 filename. If the content is not application/octet-stream, then
258 will check to see if the content is a message. If
261 will use the value \*(lq+\*(rq. As a last resort,
263 will use the value \*(lq%m%P.%s\*(rq.
265 Example profile entries might be:
269 mhstore-store-text: %m%P.txt
270 mhstore-store-text: +inbox
271 mhstore-store-message/partial: +
272 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
273 mhstore-store-image/jpeg: %m%P.jpg
274 mhstore-store-application/PostScript: %m%P.ps
278 .SS "Overwriting Existing Files"
281 switch controls whether
283 should overwrite existing files. The allowed values for this switch
284 and corresponding behavior when
286 encounters an existing file are:
291 always Overwrite existing file (default)
292 auto Create new file of form name-n.extension
293 suffix Create new file of form name.extension.n
294 ask Prompt the user to specify whether or not to overwrite
296 never Do not overwrite existing file
305 is the lowest unused number, starting from one, in the same form. If
306 a filename does not have an extension (following a '.'), then
310 create a new file of the form
320 will be the number of files that were requested but not stored.
324 if standard input is connected to a terminal,
325 the user is prompted to respond
330 to whether the file should be overwritten. The responses
331 can be abbreviated. If the user responds with
335 prompts the user for the name of the new file to be created. If it is
336 a relative path name (does not begin with '/'), then it is relative to
337 the current directory. If it is an absolute or relative path to a
338 directory that does not exist, the user will be prompted whether to
339 create the directory. If standard input is not connected to a
344 .SS "Reassembling Messages of Type message/partial"
346 is also able to reassemble messages that have been
347 split into multiple messages of type \*(lqmessage/partial\*(rq.
349 When asked to store a content containing a partial message,
351 will try to locate all of the portions and combine
352 them accordingly. The default is to store the combined parts as
353 a new message in the current folder, although this can be changed
354 using formatting strings as discussed above. Thus, if someone has
355 sent you a message in several parts (such as the output from
357 you can easily reassemble them all into a single
358 message in the following fashion:
363 msg part type/subtype size description
364 5 message/partial 47K part 1 of 4
365 6 message/partial 47K part 2 of 4
366 7 message/partial 47K part 3 of 4
367 8 message/partial 18K part 4 of 4
369 reassembling partials 5,6,7,8 to folder inbox as message 9
371 msg part type/subtype size description
372 9 application/octet-stream 118K
373 (extract with uncompress | tar xvpf -)
379 This will store exactly one message, containing the sum of the
380 parts. It doesn't matter whether the partials are specified in
383 will sort the partials, so that they
384 are combined in the correct order. But if
387 locate every partial necessary to reassemble the message, it will
389 .SS "External Access"
390 For contents of type message/external-body,
391 \fImhstore\fR supports these access-types:
406 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
408 will look for the \*(lqnmh-access-ftp\*(rq
412 nmh-access-ftp: myftp.sh
415 to determine the pathname of a program to perform the FTP retrieval.
416 This program is invoked with these arguments:
420 domain name of FTP-site
426 \*(lqascii\*(rq or \*(lqbinary\*(rq
430 The program should terminate with an exit status of zero if the
431 retrieval is successful, and a non-zero exit status otherwise.
433 For the \*(lqurl\*(rq access types,
435 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
438 nmh-access-url: curl -l
441 to determine the program to use to perform the HTTP retrieval. This program
442 is invoked with one argument: the URL of the content to retrieve. The program
443 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.
445 .SS "The Content Cache"
448 encounters an external content containing a
449 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
450 depending on the caching behavior of
452 the content might be read from or written to a cache.
454 The caching behavior of
456 is controlled with the
460 switches, which define the policy for reading from,
461 and writing to, the cache, respectively. One of four policies may be
462 specified: \*(lqpublic\*(rq, indicating that
465 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
468 should make use of the user's private content cache;
469 \*(lqnever\*(rq, indicating that
471 should never make use of
472 caching; and, \*(lqask\*(rq, indicating that
476 There are two directories where contents may be cached: the profile entry
477 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
478 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
479 private contents. The former should be an absolute (rooted) directory
488 might be used if you didn't care that the cache got wiped after each
489 reboot of the system. The latter is interpreted relative to the user's
490 nmh directory, if not rooted, e.g.,
493 nmh-private-cache: .cache
496 (which is the default value).
497 .SS "User Environment"
498 Because the display environment in which
500 operates may vary for
503 will look for the environment variable
505 If present, this specifies the name of an additional
506 user profile which should be read. Hence, when a user logs in on a
507 particular machine, this environment variable should be set to
508 refer to a file containing definitions useful for that machine.
511 will attempt to consult one other additional
515 %etcdir%/mhn.defaults
518 which is created automatically during
523 looks for additional profile files in multiple locations: absolute
524 pathnames are accessed directly, tilde expansion is done on usernames,
525 and files are searched for in the user's
527 directory as specified in their profile. If not found there, the directory
528 .RI \*(lq %etcdir% \*(rq
533 .ta \w'%etcdir%/ExtraBigFileName 'u
534 ^$HOME/\&.mh\(ruprofile~^The user profile
535 ^$MHSTORE~^Additional profile entries
536 ^%etcdir%/mhn.defaults~^System default MIME profile entries
538 .SH "PROFILE COMPONENTS"
542 .ta \w'ExtraBigProfileName 'u
543 ^Path:~^To determine the user's nmh directory
544 ^Current\-Folder:~^To find the default current folder
545 ^nmh-access-ftp:~^Program to retrieve contents via FTP
546 ^nmh-access-url:~^Program to retrieve contents via HTTP
547 ^nmh-cache~^Public directory to store cached external contents
548 ^nmh-private-cache~^Personal directory to store cached external contents
549 ^nmh-storage~^Directory to store contents
550 ^mhstore-store-<type>*~^Template for storing contents
559 .RB ` +folder "' defaults to the current folder"
560 .RB ` msgs "' defaults to cur"
562 .RB ` \-clobber\ always '
564 .RB ` \-rcache\ ask '
565 .RB ` \-wcache\ ask '
567 If a folder is given, it will become the current folder. The last
568 message selected will become the current message.
570 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob