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
71 message. It should NOT be in mail drop format (to convert a file in
72 mail drop format to a folder of
77 A part specification consists of a series of numbers separated by
78 dots. For example, in a multipart content containing three parts,
79 these would be named as 1, 2, and 3, respectively. If part 2 was also
80 a multipart content containing two parts, these would be named as 2.1
81 and 2.2, respectively. Note that the
83 switch is effective only for messages containing a multipart content.
84 If a message has some other kind of content, or if the part is itself
85 another multipart content, the
87 switch will not prevent the content from being acted upon.
91 switch can also be used to restrict (or, when used in conjunction with
93 to further restrict) the selection of parts according to content type.
96 switches part will only select the first match from a
97 multipart/alternative, even if there is more than one
98 subpart that matches (one of) the given content type(s).
104 switches alone will cause either to select the part(s) they match.
105 Using them together will select only the part(s) matched by both
106 (sets of) switches. In other words, the result is the intersection,
107 and not the union, of their separate match results.
109 A content specification consists of a content type and a subtype.
110 The initial list of \*(lqstandard\*(rq content types and subtypes can
111 be found in RFC 2046.
113 A list of commonly used contents is briefly reproduced here:
117 .ta \w'application 'u
121 multipart mixed, alternative, digest, parallel
122 message rfc822, partial, external-body
123 application octet-stream, postscript
130 A legal MIME message must contain a subtype specification.
132 To specify a content, regardless of its subtype, just use the name
133 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
134 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
135 Note that regardless of the values given to the
137 switch, a multipart content (of any subtype listed above) is always acted
138 upon. Further note that if the
140 switch is used, and it is desirable to act on a message/external-body
143 switch must be used twice: once for message/external-body and once for
144 the content externally referenced.
148 switch will alter the part-ordering of multipart/alternative MIME sections
149 in order to override the sender-imposed default ordering.
152 switch is functionally most important for
154 but is also implemented in
158 to make common part-numbering possible across all three programs.
163 for more information on
165 .SS "Checking the Contents"
170 to check each content for an integrity checksum.
171 If a content has such a checksum (specified as a Content-MD5 header
174 will attempt to verify the integrity of the content.
175 .SS "Storing the Contents"
177 will store the contents of the named messages in
178 \*(lqnative\*(rq (decoded) format. Two things must be determined:
179 the directory in which to store the content, and the filenames.
180 Files are written in the directory given by the
181 \*(lqnmh-storage\*(rq profile entry, e.g.,
187 If this entry isn't present, the current working directory is used.
191 switch is given, its argument is used for the filename to store all
192 of the content, with \*(lq-\*(rq indicating standard output. If the
194 switch is given, then
196 will check if the message contains information indicating the filename
197 that should be used to store the content. This information should be
198 specified as the \*(lqfilename\*(rq attribute in the
199 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
200 attribute in the \*(lqContent-Type\*(rq header for the content you are
201 storing. For security reasons, this filename will be ignored if it
202 begins with the character '/', '.', '|', or '!', or if it contains the
203 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
206 switch setting other than the default of \*(lqalways\*(rq to avoid
207 overwriting existing files.
211 switch is not given (or is being ignored for security reasons) then
213 will look in the user's profile for a \*(lqformatting string\*(rq to
214 determine how the different contents should be stored. First,
216 will look for an entry of the form:
219 mhstore-store-<type>/<subtype>
222 to determine the formatting string. If this isn't found,
224 will look for an entry of the form:
230 to determine the formatting string.
232 If the formatting string starts with a \*(lq+\*(rq character, then
233 content is stored in the named folder. A formatting string consisting
234 solely of a \*(lq+\*(rq character is interpreted to be the current
237 If the formatting string consists solely of a \*(lq-\*(rq character,
238 then the content is sent to the standard output.
240 If the formatting string starts with a '|', then it represents
243 to execute which should ultimately store the content.
244 The content will be passed to the standard input of the command.
245 Before the command is executed,
247 will change to the appropriate directory, and any escapes (given below)
248 in the formatting string will be expanded.
249 The use of the \*(lq%a\*(rq sequence is not recommended because
250 the user has no control over the Content-Type parameter data.
252 Otherwise, the formatting string will represent a pathname in which
253 to store the content. If the formatting string starts with a '/',
254 then the content will be stored in the full path given, else the
255 file name will be relative to the value of \*(lqnmh-storage\*(rq or
256 the current working directory. Any escapes (given below) will be
257 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
258 is not an absolute path, it will be relative to the folder that
259 contains the message(s).
261 A command or pathname formatting string may contain the following
262 escapes. If the content isn't part of a multipart (of any subtype
263 listed above) content, the p-escapes are ignored.
268 %a Parameters from Content-Type (only valid with command)
269 %m Insert message number
270 %P Insert part number with leading dot
271 %p Insert part number without leading dot
272 %t Insert content type
273 %s Insert content subtype
274 %% Insert character %
278 If no formatting string is found,
280 will check to see if the content is application/octet-stream with parameter
281 \*(lqtype=tar\*(rq. If so,
283 will choose an appropriate filename. If the content is not
284 application/octet-stream, then
286 will check to see if the content is a message. If so,
288 will use the value \*(lq+\*(rq. As a last resort,
290 will use the value \*(lq%m%P.%s\*(rq.
292 Example profile entries might be:
296 mhstore-store-text: %m%P.txt
297 mhstore-store-text: +inbox
298 mhstore-store-message/partial: +
299 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
300 mhstore-store-image/jpeg: %m%P.jpg
301 mhstore-store-application/PostScript: %m%P.ps
309 to print out the names of files that it stores. For backward
310 compatibility, it is the default. The
312 switch suppresses these printouts.
313 .SS "Overwriting Existing Files"
316 switch controls whether
318 should overwrite existing files. The allowed values for this switch
319 and corresponding behavior when
321 encounters an existing file are:
326 always Overwrite existing file (default)
327 auto Create new file of form name-n.extension
328 suffix Create new file of form name.extension.n
329 ask Prompt the user to specify whether or not to overwrite
331 never Do not overwrite existing file
340 is the lowest unused number, starting from one, in the same form. If
341 a filename does not have an extension (following a '.'), then
345 create a new file of the form
355 will be the number of files that were requested but not stored.
359 if standard input is connected to a terminal, the user is prompted to
365 to whether the file should be overwritten. The responses
366 can be abbreviated. If the user responds with
370 prompts the user for the name of the new file to be created. If it is
371 a relative path name (does not begin with '/'), then it is relative to
372 the current directory. If it is an absolute or relative path to a
373 directory that does not exist, the user will be prompted whether to
374 create the directory. If standard input is not connected to a
379 .SS "Reassembling Messages of Type message/partial"
381 is also able to reassemble messages that have been
382 split into multiple messages of type \*(lqmessage/partial\*(rq.
384 When asked to store a content containing a partial message,
386 will try to locate all of the portions and combine them accordingly.
387 The default is to store the combined parts as a new message in the
388 current folder, although this can be changed using formatting
389 strings as discussed above. Thus, if someone has sent you a
390 message in several parts (such as the output from
392 you can easily reassemble them into a single message in the
398 msg part type/subtype size description
399 5 message/partial 47K part 1 of 4
400 6 message/partial 47K part 2 of 4
401 7 message/partial 47K part 3 of 4
402 8 message/partial 18K part 4 of 4
404 reassembling partials 5,6,7,8 to folder inbox as message 9
406 msg part type/subtype size description
407 9 application/octet-stream 118K
408 (extract with uncompress | tar xvpf -)
414 This will store exactly one message, containing the sum of the
415 parts. It doesn't matter whether the partials are specified in
418 will sort the partials, so that they are combined in the correct
421 can not locate every partial necessary to reassemble the message,
422 it will not store anything.
423 .SS "External Access"
424 For contents of type message/external-body,
425 \fImhstore\fR supports these access-types:
439 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
441 will look for the \*(lqnmh-access-ftp\*(rq
445 nmh-access-ftp: myftp.sh
448 to determine the pathname of a program to perform the FTP retrieval.
449 This program is invoked with these arguments:
453 domain name of FTP-site
459 \*(lqascii\*(rq or \*(lqbinary\*(rq
463 The program should terminate with an exit status of zero if the
464 retrieval is successful, and a non-zero exit status otherwise.
466 For the \*(lqurl\*(rq access types,
468 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
471 nmh-access-url: curl -L
474 to determine the program to use to perform the HTTP retrieval. This program
475 is invoked with one argument: the URL of the content to retrieve. The program
476 should write the content to standard out, and should terminate with a status
477 of zero if the retrieval is successful and a non-zero exit status otherwise.
478 .SS "The Content Cache"
481 encounters an external content containing a
482 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
483 depending on the caching behavior of
485 the content might be read from or written to a cache.
487 The caching behavior of
489 is controlled with the
493 switches, which define the policy for reading from, and writing to, the cache,
494 respectively. One of four policies may be
495 specified: \*(lqpublic\*(rq, indicating that
498 of a publicly-accessible content cache; \*(lqprivate\*(rq, indicating that
500 should make use of the user's private content cache;
501 \*(lqnever\*(rq, indicating that
503 should never make use of caching; and, \*(lqask\*(rq, indicating that
507 There are two directories where contents may be cached: the profile entry
508 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
509 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
510 private contents. The former should be an absolute (rooted) directory
519 might be used if you didn't care that the cache got wiped after each
520 reboot of the system. The latter is interpreted relative to the user's
521 nmh directory, if not rooted, e.g.,
524 nmh-private-cache: .cache
527 (which is the default value).
528 .SS "User Environment"
529 Because the environment in which
531 operates may vary for different machines,
533 will look for the environment variable MHSTORE .
534 If present, this specifies the name of an additional user profile
535 which should be read. Hence, when a user logs in on a particular
536 machine, this environment variable should be set to refer to a
537 file containing definitions useful for that machine. Finally,
539 will attempt to consult
542 %nmhetcdir%/mhn.defaults
545 which is created automatically during
549 See "Profile Lookup" in
551 for the profile search order, and for how duplicate entries are treated.
553 .SS Decoding RFC 2047-encoded file names
554 The improper RFC 2047 encoding of file name parameters can be replaced
555 with correct RFC 2231 encoding using
557 either permanently or ephemerally, e.g.,
561 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
567 is not necessary, though recommended to avoid silently overwriting an existing
571 looks for additional profile files in multiple locations: absolute
572 pathnames are accessed directly, tilde expansion is done on usernames,
573 and files are searched for in the user's
575 directory as specified in their profile. If not found there, the directory
576 .RI \*(lq %nmhetcdir% \*(rq
581 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
582 ^$HOME/.mh_profile~^The user profile
583 ^$MHSTORE~^Additional profile entries
584 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
586 .SH "PROFILE COMPONENTS"
590 .ta \w'ExtraBigProfileName 'u
591 ^Path:~^To determine the user's nmh directory
592 ^Current\-Folder:~^To find the default current folder
593 ^nmh-access-ftp:~^Program to retrieve contents via FTP
594 ^nmh-access-url:~^Program to retrieve contents via HTTP
595 ^nmh-cache~^Public directory to store cached external contents
596 ^nmh-private-cache~^Personal directory to store cached external contents
597 ^nmh-storage~^Directory to store contents
598 ^mhstore-store-<type>*~^Template for storing contents
608 .RB ` +folder "' defaults to the current folder"
609 .RB ` msgs "' defaults to cur"
611 .RB ` \-clobber\ always '
613 .RB ` \-rcache\ ask '
614 .RB ` \-wcache\ ask '
617 If a folder is given, it will become the current folder. The last
618 message selected will become the current message.
620 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob