1 .TH MHSTORE %manext1% 2015-02-06 "%nmhversion%"
6 mhstore \- store contents of nmh MIME messages into files
28 .RB [ \-auto " | " \-noauto ]
30 .IR always " | " auto " | " suffix " | " ask " | " never ]
35 .RB [ \-check " | " \-nocheck ]
36 .RB [ \-verbose " | " \-noverbose ]
41 command allows you to store the contents of a collection of MIME
42 (multi-media) messages into files or other messages.
45 manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
49 will store all the parts of each message.
50 Each part will be stored in a separate file. The header fields of
51 the message are not stored. By using the
56 switches, you may limit and reorder the set of parts to be stored,
57 based on part number and/or content type.
64 to use the specified file as the source message, rather than a message
65 from a folder. If you specify this file as \*(lq-\*(rq, then
67 will accept the source message on the standard input. Note that the
68 file, or input from standard input, should be a validly formatted
69 message, just like any other
73 be in mail drop format (to convert a file in
74 mail drop format to a folder of
79 A part specification consists of a series of numbers separated by
80 dots. For example, in a multipart content containing three parts,
81 these would be named as 1, 2, and 3, respectively. If part 2 was also
82 a multipart content containing two parts, these would be named as 2.1
83 and 2.2, respectively. Note that the
85 switch is effective only for messages containing a multipart content.
86 If a message has some other kind of content, or if the part is itself
87 another multipart content, the
89 switch will not prevent the content from being acted upon.
93 switch can also be used to restrict (or, when used in conjunction with
95 to further restrict) the selection of parts according to content type.
98 switches part will only select the first match from a
99 multipart/alternative, even if there is more than one
100 subpart that matches (one of) the given content type(s).
106 switches alone will cause either to select the part(s) they match.
107 Using them together will select only the part(s) matched by both
108 (sets of) switches. In other words, the result is the intersection,
109 and not the union, of their separate match results.
111 A content specification consists of a content type and a subtype.
112 The initial list of \*(lqstandard\*(rq content types and subtypes can
113 be found in RFC 2046.
115 A list of commonly used contents is briefly reproduced here:
119 .ta \w'application 'u
123 multipart mixed, alternative, digest, parallel
124 message rfc822, partial, external-body
125 application octet-stream, postscript
132 A legal MIME message must contain a subtype specification.
134 To specify a content, regardless of its subtype, just use the name
135 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
136 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
137 Note that regardless of the values given to the
139 switch, a multipart content (of any subtype listed above) is always acted
140 upon. Further note that if the
142 switch is used, and it is desirable to act on a message/external-body
145 switch must be used twice: once for message/external-body and once for
146 the content externally referenced.
150 switch will alter the part-ordering of multipart/alternative MIME sections
151 in order to override the sender-imposed default ordering.
154 switch is functionally most important for
156 but is also implemented in
160 to make common part-numbering possible across all three programs.
163 switches will have the highest priority. This allows the command line
164 switches to override profile entries.
169 for more information on
171 .SS "Checking the Contents"
176 to check each content for an integrity checksum.
177 If a content has such a checksum (specified as a Content-MD5 header
180 will attempt to verify the integrity of the content.
181 .SS "Storing the Contents"
183 will store the contents of the named messages in
184 \*(lqnative\*(rq (decoded) format. Two things must be determined:
185 the directory in which to store the content, and the filenames.
186 Files are written in the directory given by the
187 \*(lqnmh-storage\*(rq profile entry, e.g.,
193 If this entry isn't present, the current working directory is used.
197 switch is given, its argument is used for the filename to store all
198 of the content, with \*(lq-\*(rq indicating standard output. If the
200 switch is given, then
202 will check if the message contains information indicating the filename
203 that should be used to store the content. This information should be
204 specified as the \*(lqfilename\*(rq attribute in the
205 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
206 attribute in the \*(lqContent-Type\*(rq header for the content you are
207 storing. For security reasons, this filename will be ignored if it
208 begins with the character '/', '.', '|', or '!', or if it contains the
209 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
212 switch setting other than the default of \*(lqalways\*(rq to avoid
213 overwriting existing files.
217 switch is not given (or is being ignored for security reasons) then
219 will look in the user's profile for a \*(lqformatting string\*(rq to
220 determine how the different contents should be stored. First,
222 will look for an entry of the form:
225 mhstore-store-<type>/<subtype>
228 to determine the formatting string. If this isn't found,
230 will look for an entry of the form:
236 to determine the formatting string.
238 If the formatting string starts with a \*(lq+\*(rq character, then
239 content is stored in the named folder. A formatting string consisting
240 solely of a \*(lq+\*(rq character is interpreted to be the current
243 If the formatting string consists solely of a \*(lq-\*(rq character,
244 then the content is sent to the standard output.
246 If the formatting string starts with a '|', then it represents
249 to execute which should ultimately store the content.
250 The content will be passed to the standard input of the command.
251 Before the command is executed,
253 will change to the appropriate directory, and any escapes (given below)
254 in the formatting string will be expanded.
255 The use of the \*(lq%a\*(rq sequence is not recommended because
256 the user has no control over the Content-Type parameter data.
258 Otherwise, the formatting string will represent a pathname in which
259 to store the content. If the formatting string starts with a '/',
260 then the content will be stored in the full path given, else the
261 file name will be relative to the value of \*(lqnmh-storage\*(rq or
262 the current working directory. Any escapes (given below) will be
263 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
264 is not an absolute path, it will be relative to the folder that
265 contains the message(s).
267 A command or pathname formatting string may contain the following
268 escapes. If the content isn't part of a multipart (of any subtype
269 listed above) content, the p-escapes are ignored.
274 %a Parameters from Content-Type (only valid with command)
275 %m Insert message number
276 %P Insert part number with leading dot
277 %p Insert part number without leading dot
278 %t Insert content type
279 %s Insert content subtype
280 %% Insert character %
284 If no formatting string is found,
286 will check to see if the content is application/octet-stream with parameter
287 \*(lqtype=tar\*(rq. If so,
289 will choose an appropriate filename. If the content is not
290 application/octet-stream, then
292 will check to see if the content is a message. If so,
294 will use the value \*(lq+\*(rq. As a last resort,
296 will use the value \*(lq%m%P.%s\*(rq.
298 Example profile entries might be:
302 mhstore-store-text: %m%P.txt
303 mhstore-store-text: +inbox
304 mhstore-store-message/partial: +
305 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
306 mhstore-store-image/jpeg: %m%P.jpg
307 mhstore-store-application/PostScript: %m%P.ps
315 to print out the names of files that it stores. For backward
316 compatibility, it is the default. The
318 switch suppresses these printouts.
319 .SS "Overwriting Existing Files"
322 switch controls whether
324 should overwrite existing files. The allowed values for this switch
325 and corresponding behavior when
327 encounters an existing file are:
332 always Overwrite existing file (default)
333 auto Create new file of form name-n.extension
334 suffix Create new file of form name.extension.n
335 ask Prompt the user to specify whether or not to overwrite
337 never Do not overwrite existing file
346 is the lowest unused number, starting from one, in the same form. If
347 a filename does not have an extension (following a '.'), then
351 create a new file of the form
361 will be the number of files that were requested but not stored.
365 if standard input is connected to a terminal, the user is prompted to
371 to whether the file should be overwritten. The responses
372 can be abbreviated. If the user responds with
376 prompts the user for the name of the new file to be created. If it is
377 a relative path name (does not begin with '/'), then it is relative to
378 the current directory. If it is an absolute or relative path to a
379 directory that does not exist, the user will be prompted whether to
380 create the directory. If standard input is not connected to a
385 .SS "Reassembling Messages of Type message/partial"
387 is also able to reassemble messages that have been
388 split into multiple messages of type \*(lqmessage/partial\*(rq.
390 When asked to store a content containing a partial message,
392 will try to locate all of the portions and combine them accordingly.
393 The default is to store the combined parts as a new message in the
394 current folder, although this can be changed using formatting
395 strings as discussed above. Thus, if someone has sent you a
396 message in several parts (such as the output from
398 you can easily reassemble them into a single message in the
404 msg part type/subtype size description
405 5 message/partial 47K part 1 of 4
406 6 message/partial 47K part 2 of 4
407 7 message/partial 47K part 3 of 4
408 8 message/partial 18K part 4 of 4
410 reassembling partials 5,6,7,8 to folder inbox as message 9
412 msg part type/subtype size description
413 9 application/octet-stream 118K
414 (extract with uncompress | tar xvpf -)
420 This will store exactly one message, containing the sum of the
421 parts. It doesn't matter whether the partials are specified in
424 will sort the partials, so that they are combined in the correct
427 can not locate every partial necessary to reassemble the message,
428 it will not store anything.
429 .SS "External Access"
430 For contents of type message/external-body,
431 \fImhstore\fR supports these access-types:
445 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
447 will look for the \*(lqnmh-access-ftp\*(rq
451 nmh-access-ftp: myftp.sh
454 to determine the pathname of a program to perform the FTP retrieval.
455 This program is invoked with these arguments:
459 domain name of FTP-site
465 \*(lqascii\*(rq or \*(lqbinary\*(rq
469 The program should terminate with an exit status of zero if the
470 retrieval is successful, and a non-zero exit status otherwise.
472 For the \*(lqurl\*(rq access types,
474 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
477 nmh-access-url: curl -L
480 to determine the program to use to perform the HTTP retrieval. This program
481 is invoked with one argument: the URL of the content to retrieve. The program
482 should write the content to standard out, and should terminate with a status
483 of zero if the retrieval is successful and a non-zero exit status otherwise.
484 .SS "The Content Cache"
487 encounters an external content containing a
488 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
489 depending on the caching behavior of
491 the content might be read from or written to a cache.
493 The caching behavior of
495 is controlled with the
499 switches, which define the policy for reading from, and writing to, the cache,
500 respectively. One of four policies may be
501 specified: \*(lqpublic\*(rq, indicating that
504 of a publicly-accessible content cache; \*(lqprivate\*(rq, indicating that
506 should make use of the user's private content cache;
507 \*(lqnever\*(rq, indicating that
509 should never make use of caching; and, \*(lqask\*(rq, indicating that
513 There are two directories where contents may be cached: the profile entry
514 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
515 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
516 private contents. The former should be an absolute (rooted) directory
525 might be used if you didn't care that the cache got wiped after each
526 reboot of the system. The latter is interpreted relative to the user's
527 nmh directory, if not rooted, e.g.,
530 nmh-private-cache: .cache
533 (which is the default value).
534 .SS "User Environment"
535 Because the environment in which
537 operates may vary for different machines,
539 will look for the environment variable MHSTORE .
540 If present, this specifies the name of an additional user profile
541 which should be read. Hence, when a user logs in on a particular
542 machine, this environment variable should be set to refer to a
543 file containing definitions useful for that machine. Finally,
545 will attempt to consult
548 %nmhetcdir%/mhn.defaults
551 which is created automatically during
555 See "Profile Lookup" in
557 for the profile search order, and for how duplicate entries are treated.
559 .SS Decoding RFC 2047-encoded file names
560 The improper RFC 2047 encoding of file name parameters can be replaced
561 with correct RFC 2231 encoding using
563 either permanently or ephemerally, e.g.,
567 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
573 is not necessary, though recommended to avoid silently overwriting an existing
577 looks for additional profile files in multiple locations: absolute
578 pathnames are accessed directly, tilde expansion is done on usernames,
579 and files are searched for in the user's
581 directory as specified in their profile. If not found there, the directory
582 .RI \*(lq %nmhetcdir% \*(rq
587 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
588 ^$HOME/.mh_profile~^The user profile
589 ^$MHSTORE~^Additional profile entries
590 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
592 .SH "PROFILE COMPONENTS"
596 .ta \w'ExtraBigProfileName 'u
597 ^Path:~^To determine the user's nmh directory
598 ^Current\-Folder:~^To find the default current folder
599 ^nmh-access-ftp:~^Program to retrieve contents via FTP
600 ^nmh-access-url:~^Program to retrieve contents via HTTP
601 ^nmh-cache~^Public directory to store cached external contents
602 ^nmh-private-cache~^Personal directory to store cached external contents
603 ^nmh-storage~^Directory to store contents
604 ^mhstore-store-<type>*~^Template for storing contents
614 .RB ` +folder "' defaults to the current folder"
615 .RB ` msgs "' defaults to cur"
617 .RB ` \-clobber\ always '
619 .RB ` \-rcache\ ask '
620 .RB ` \-wcache\ ask '
623 If a folder is given, it will become the current folder. The last
624 message selected will become the current message.
626 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob