1 .TH MHSTORE %manext1% "October 7, 2016" "%nmhversion%"
6 mhstore \- store contents of 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
42 collection of MIME (multi-media) messages into files or other
46 manipulates multi-media messages as specified in
51 will store all the parts of each message.
52 Each part will be store in a separate file. The header fields of
53 the message are not stored. By using the
58 switches, you may limit and reorder the set of parts to be stored,
59 based on part number and/or content type.
67 file as the source message, rather than a message from a folder.
68 If you specify this file as \*(lq-\*(rq, then
71 accept the source message on the standard input. Note that the
72 file, or input from standard input should be a validly formatted
73 message, just like any other
77 be in mail drop format (to convert a file in mail drop format to
83 A part specification consists of a series of numbers separated by
84 dots. For example, in a multipart content containing three parts,
85 these would be named as 1, 2, and 3, respectively. If part 2 was also
86 a multipart content containing two parts, these would be named as 2.1
87 and 2.2, respectively. Note that the
89 switch is effective for only messages containing a multipart content.
90 If a message has some other kind of content, or if the part is itself
91 another multipart content, the
93 switch will not prevent the content from being acted upon.
97 switch can also be used to restrict (or, when used in conjunction with
99 to further restrict) the selection of parts according to content type.
102 switches part will only select the first match
103 from a multipart/alternative, even if there is more than one
104 subpart that matches (one of) the given content type(s).
110 switches alone will cause either to select
111 the part(s) they match. Using them together will select only
112 the part(s) matched by both (sets of) switches. In other
113 words, the result is the intersection, and not the union, of their
114 separate match results.
116 A content specification consists of a content type and a subtype.
117 The initial list of \*(lqstandard\*(rq content types and subtypes can
118 be found in RFC 2046.
120 A list of commonly used contents is briefly reproduced here:
124 .ta \w'application 'u
128 multipart mixed, alternative, digest, parallel
129 message rfc822, partial, external-body
130 application octet-stream, postscript
137 A legal MIME message must contain a subtype specification.
139 To specify a content, regardless of its subtype, just use the name
140 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
141 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
142 Note that regardless of the values given to the
145 a multipart content (of any subtype listed above) is always acted
146 upon. Further note that if the
148 switch is used, and it is
149 desirable to act on a message/external-body content, then the
151 switch must be used twice: once for message/external-body
152 and once for the content externally referenced.
156 switch will alter the part ordering of multipart/alternative MIME sections
157 in order to override the sender-imposed default ordering.
160 switch is functionally most important for
162 but is also implemented in
166 to make common part numbering possible across all three programs.
171 for more information on
173 .SS "Checking the Contents"
178 to check each content for
179 an integrity checksum. If a content has such a checksum (specified
180 as a Content-MD5 header field), then
183 verify the integrity of the content.
184 .SS "Storing the Contents"
186 will store the contents of the named messages in
187 \*(lqnative\*(rq (decoded) format. Two things must be determined:
188 the directory to store the content, and the filenames. Files are
189 written in the directory given by the \*(lqnmh-storage\*(rq profile
196 If this entry isn't present,
197 the current working directory is used.
201 switch is given, its argument is used for the filename to store all
202 of the content, with \*(lq-\*(rq indicating standard output. If the
204 switch is given, then
206 will check if the message contains information indicating the filename
207 that should be used to store the content. This information should be
208 specified as the \*(lqfilename\*(rq attribute in the
209 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
210 attribute in the \*(lqContent-Type\*(rq header for the content you are
211 storing. For security reasons, this filename will be ignored if it
212 begins with the character '/', '.', '|', or '!', or if it contains the
213 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
216 switch setting other than the default of \*(lqalways\*(rq to avoid
217 overwriting existing files.
221 switch is not given (or is being ignored for security
224 will look in the user's profile for a
225 \*(lqformatting string\*(rq to determine how the different contents
226 should be stored. First,
228 will look for an entry of
232 mhstore-store-<type>/<subtype>
235 to determine the formatting string. If this isn't found,
237 will look for an entry of the form:
243 to determine the formatting string.
245 If the formatting string starts with a \*(lq+\*(rq character, then
246 content is stored in the named folder. A formatting string consisting
247 solely of a \*(lq+\*(rq character is interpreted to be the current
250 If the formatting string consists solely of a \*(lq-\*(rq character,
251 then the content is sent to the standard output.
253 If the formatting string starts with a '|', then it represents
256 to execute which should
257 ultimately store the content. The content will be passed to the
258 standard input of the command. Before the command is executed,
260 will change to the appropriate directory, and any
261 escapes (given below) in the formatting string will be expanded.
262 The use of the \*(lq%a\*(rq sequence is not recommended because
263 the user has no control over the Content-Type parameter data.
265 Otherwise the formatting string will represent a pathname in which
266 to store the content. If the formatting string starts with a '/',
267 then the content will be stored in the full path given, else the
268 file name will be relative to the value of \*(lqnmh-storage\*(rq or
269 the current working directory. Any escapes (given below) will be
270 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
271 is not an absolute path, it will be relative to the folder that
272 contains the message(s).
274 A command or pathname formatting string may contain the following
275 escapes. If the content isn't part of a multipart (of any subtype
276 listed above) content, the p-escapes are ignored.
281 %a Parameters from Content-Type (only valid with command)
282 %m Insert message number
283 %P Insert part number with leading dot
284 %p Insert part number without leading dot
285 %t Insert content type
286 %s Insert content subtype
287 %% Insert character %
291 If no formatting string is found,
294 if the content is application/octet-stream with parameter
295 \*(lqtype=tar\*(rq. If so,
297 will choose an appropriate
298 filename. If the content is not application/octet-stream, then
300 will check to see if the content is a message. If
303 will use the value \*(lq+\*(rq. As a last resort,
305 will use the value \*(lq%m%P.%s\*(rq.
307 Example profile entries might be:
311 mhstore-store-text: %m%P.txt
312 mhstore-store-text: +inbox
313 mhstore-store-message/partial: +
314 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
315 mhstore-store-image/jpeg: %m%P.jpg
316 mhstore-store-application/PostScript: %m%P.ps
324 to print out the names of files that it stores. For backward
325 compatibility, it is the default. The
327 switch suppresses these printouts.
329 .SS "Overwriting Existing Files"
332 switch controls whether
334 should overwrite existing files. The allowed values for this switch
335 and corresponding behavior when
337 encounters an existing file are:
342 always Overwrite existing file (default)
343 auto Create new file of form name-n.extension
344 suffix Create new file of form name.extension.n
345 ask Prompt the user to specify whether or not to overwrite
347 never Do not overwrite existing file
356 is the lowest unused number, starting from one, in the same form. If
357 a filename does not have an extension (following a '.'), then
361 create a new file of the form
371 will be the number of files that were requested but not stored.
375 if standard input is connected to a terminal,
376 the user is prompted to respond
381 to whether the file should be overwritten. The responses
382 can be abbreviated. If the user responds with
386 prompts the user for the name of the new file to be created. If it is
387 a relative path name (does not begin with '/'), then it is relative to
388 the current directory. If it is an absolute or relative path to a
389 directory that does not exist, the user will be prompted whether to
390 create the directory. If standard input is not connected to a
395 .SS "Reassembling Messages of Type message/partial"
397 is also able to reassemble messages that have been
398 split into multiple messages of type \*(lqmessage/partial\*(rq.
400 When asked to store a content containing a partial message,
402 will try to locate all of the portions and combine
403 them accordingly. The default is to store the combined parts as
404 a new message in the current folder, although this can be changed
405 using formatting strings as discussed above. Thus, if someone has
406 sent you a message in several parts (such as the output from
408 you can easily reassemble them all into a single
409 message in the following fashion:
414 msg part type/subtype size description
415 5 message/partial 47K part 1 of 4
416 6 message/partial 47K part 2 of 4
417 7 message/partial 47K part 3 of 4
418 8 message/partial 18K part 4 of 4
420 reassembling partials 5,6,7,8 to folder inbox as message 9
422 msg part type/subtype size description
423 9 application/octet-stream 118K
424 (extract with uncompress | tar xvpf -)
430 This will store exactly one message, containing the sum of the
431 parts. It doesn't matter whether the partials are specified in
434 will sort the partials, so that they
435 are combined in the correct order. But if
438 locate every partial necessary to reassemble the message, it will
440 .SS "External Access"
441 For contents of type message/external-body,
442 \fImhstore\fR supports these access-types:
457 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
459 will look for the \*(lqnmh-access-ftp\*(rq
463 nmh-access-ftp: myftp.sh
466 to determine the pathname of a program to perform the FTP retrieval.
467 This program is invoked with these arguments:
471 domain name of FTP-site
477 \*(lqascii\*(rq or \*(lqbinary\*(rq
481 The program should terminate with an exit status of zero if the
482 retrieval is successful, and a non-zero exit status otherwise.
484 For the \*(lqurl\*(rq access types,
486 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
489 nmh-access-url: curl -L
492 to determine the program to use to perform the HTTP retrieval. This program
493 is invoked with one argument: the URL of the content to retrieve. The program
494 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.
496 .SS "The Content Cache"
499 encounters an external content containing a
500 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
501 depending on the caching behavior of
503 the content might be read from or written to a cache.
505 The caching behavior of
507 is controlled with the
511 switches, which define the policy for reading from,
512 and writing to, the cache, respectively. One of four policies may be
513 specified: \*(lqpublic\*(rq, indicating that
516 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
519 should make use of the user's private content cache;
520 \*(lqnever\*(rq, indicating that
522 should never make use of
523 caching; and, \*(lqask\*(rq, indicating that
527 There are two directories where contents may be cached: the profile entry
528 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
529 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
530 private contents. The former should be an absolute (rooted) directory
539 might be used if you didn't care that the cache got wiped after each
540 reboot of the system. The latter is interpreted relative to the user's
541 nmh directory, if not rooted, e.g.,
544 nmh-private-cache: .cache
547 (which is the default value).
548 .SS "User Environment"
549 Because the environment in which
551 operates may vary for
554 will look for the environment variable
556 If present, this specifies the name of an additional
557 user profile which should be read. Hence, when a user logs in on a
558 particular machine, this environment variable should be set to
559 refer to a file containing definitions useful for that machine.
562 will attempt to consult
565 %nmhetcdir%/mhn.defaults
568 which is created automatically during
572 See "Profile Lookup" in
574 for the profile search order, and for how duplicate entries are treated.
576 .SS Decoding RFC 2047-encoded file names
577 The improper RFC 2047 encoding of file name parameters can be replaced
578 with correct RFC 2231 encoding using
580 either permanently or ephemerally, e.g.,
584 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
590 is not necessary, though recommended to avoid silently overwriting an existing
594 looks for additional profile files in multiple locations: absolute
595 pathnames are accessed directly, tilde expansion is done on usernames,
596 and files are searched for in the user's
598 directory as specified in their profile. If not found there, the directory
599 .RI \*(lq %nmhetcdir% \*(rq
604 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
605 ^$HOME/\&.mh\(ruprofile~^The user profile
606 ^$MHSTORE~^Additional profile entries
607 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
609 .SH "PROFILE COMPONENTS"
613 .ta \w'ExtraBigProfileName 'u
614 ^Path:~^To determine the user's nmh directory
615 ^Current\-Folder:~^To find the default current folder
616 ^nmh-access-ftp:~^Program to retrieve contents via FTP
617 ^nmh-access-url:~^Program to retrieve contents via HTTP
618 ^nmh-cache~^Public directory to store cached external contents
619 ^nmh-private-cache~^Personal directory to store cached external contents
620 ^nmh-storage~^Directory to store contents
621 ^mhstore-store-<type>*~^Template for storing contents
631 .RB ` +folder "' defaults to the current folder"
632 .RB ` msgs "' defaults to cur"
634 .RB ` \-clobber\ always '
636 .RB ` \-rcache\ ask '
637 .RB ` \-wcache\ ask '
640 If a folder is given, it will become the current folder. The last
641 message selected will become the current message.
643 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob