1 .TH MHSTORE %manext1% 2015-02-06 "%nmhversion%"
6 mhstore \- store contents of nmh MIME messages into files
29 .RB [ \-auto " | " \-noauto ]
31 .IR always " | " auto " | " suffix " | " ask " | " never ]
36 .RB [ \-check " | " \-nocheck ]
37 .RB [ \-verbose " | " \-noverbose ]
42 command allows you to store the contents of a collection of MIME
43 (multi-media) messages into files or other messages.
46 manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
50 will store all the parts of each message.
51 Each part will be stored in a separate file. The header fields of
52 the message are not stored. By using the
57 switches, you may limit and reorder the set of parts to be stored,
58 based on part number and/or content type.
65 to use the specified file as the source message, rather than a message
66 from a folder. If you specify this file as \*(lq-\*(rq, then
68 will 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
75 mail drop format to a folder of
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 also
83 a multipart content containing two parts, these would be named as 2.1
84 and 2.2, respectively. Note that the
86 switch is effective only for messages containing a multipart content.
87 If a message has some other kind of content, or if the part is itself
88 another multipart content, the
90 switch will not prevent the content from being acted upon.
94 switch can also be used to restrict (or, when used in conjunction with
96 to further restrict) the selection of parts according to content type.
99 switches part will only select the first match from a
100 multipart/alternative, even if there is more than one
101 subpart that matches (one of) the given content type(s).
107 switches alone will cause either to select the part(s) they match.
108 Using them together will select only the part(s) matched by both
109 (sets of) switches. In other words, the result is the intersection,
110 and not the union, of their separate match results.
112 A content specification consists of a content type and a subtype.
113 The initial list of \*(lqstandard\*(rq content types and subtypes can
114 be found in RFC 2046.
116 A list of commonly used contents is briefly reproduced here:
120 .ta \w'application 'u
124 multipart mixed, alternative, digest, parallel
125 message rfc822, partial, external-body
126 application octet-stream, postscript
133 A legal MIME message must contain a subtype specification.
135 To specify a content, regardless of its subtype, just use the name
136 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
137 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
138 Note that regardless of the values given to the
140 switch, a multipart content (of any subtype listed above) is always acted
141 upon. Further note that if the
143 switch is used, and it is desirable to act on a message/external-body
146 switch must be used twice: once for message/external-body and once for
147 the content externally referenced.
151 switch will alter the part-ordering of multipart/alternative MIME sections
152 in order to override the sender-imposed default ordering.
155 switch is functionally most important for
157 but is also implemented in
161 to make common part-numbering possible across all three programs.
164 switches will have the highest priority. This allows the command line
165 switches to override profile entries.
170 for more information on
175 switch will cancel any previous
178 .SS "Checking the Contents"
183 to check each content for an integrity checksum.
184 If a content has such a checksum (specified as a Content-MD5 header
187 will attempt to verify the integrity of the content.
188 .SS "Storing the Contents"
190 will store the contents of the named messages in
191 \*(lqnative\*(rq (decoded) format. Two things must be determined:
192 the directory in which to store the content, and the filenames.
193 Files are written in the directory given by the
194 \*(lqnmh-storage\*(rq profile entry, e.g.,
200 If this entry isn't present, the current working directory is used.
204 switch is given, its argument is used for the filename to store all
205 of the content, with \*(lq-\*(rq indicating standard output. If the
207 switch is given, then
209 will check if the message contains information indicating the filename
210 that should be used to store the content. This information should be
211 specified as the \*(lqfilename\*(rq attribute in the
212 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
213 attribute in the \*(lqContent-Type\*(rq header for the content you are
214 storing. For security reasons, this filename will be ignored if it
215 begins with the character '/', '.', '|', or '!', or if it contains the
216 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
219 switch setting other than the default of \*(lqalways\*(rq to avoid
220 overwriting existing files.
224 switch is not given (or is being ignored for security reasons) then
226 will look in the user's profile for a \*(lqformatting string\*(rq to
227 determine how the different contents should be stored. First,
229 will look for an entry of the form:
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 ultimately store the content.
257 The content will be passed to the standard input of the command.
258 Before the command is executed,
260 will change to the appropriate directory, and any escapes (given below)
261 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,
293 will check to see if the content is application/octet-stream with parameter
294 \*(lqtype=tar\*(rq. If so,
296 will choose an appropriate filename. If the content is not
297 application/octet-stream, then
299 will check to see if the content is a message. If so,
301 will use the value \*(lq+\*(rq. As a last resort,
303 will use the value \*(lq%m%P.%s\*(rq.
305 Example profile entries might be:
309 mhstore-store-text: %m%P.txt
310 mhstore-store-text: +inbox
311 mhstore-store-message/partial: +
312 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
313 mhstore-store-image/jpeg: %m%P.jpg
314 mhstore-store-application/PostScript: %m%P.ps
322 to print out the names of files that it stores. For backward
323 compatibility, it is the default. The
325 switch suppresses these printouts.
326 .SS "Overwriting Existing Files"
329 switch controls whether
331 should overwrite existing files. The allowed values for this switch
332 and corresponding behavior when
334 encounters an existing file are:
339 always Overwrite existing file (default)
340 auto Create new file of form name-n.extension
341 suffix Create new file of form name.extension.n
342 ask Prompt the user to specify whether or not to overwrite
344 never Do not overwrite existing file
353 is the lowest unused number, starting from one, in the same form. If
354 a filename does not have an extension (following a '.'), then
358 create a new file of the form
368 will be the number of files that were requested but not stored.
372 if standard input is connected to a terminal, the user is prompted to
378 to whether the file should be overwritten. The responses
379 can be abbreviated. If the user responds with
383 prompts the user for the name of the new file to be created. If it is
384 a relative path name (does not begin with '/'), then it is relative to
385 the current directory. If it is an absolute or relative path to a
386 directory that does not exist, the user will be prompted whether to
387 create the directory. If standard input is not connected to a
392 .SS "Reassembling Messages of Type message/partial"
394 is also able to reassemble messages that have been
395 split into multiple messages of type \*(lqmessage/partial\*(rq.
397 When asked to store a content containing a partial message,
399 will try to locate all of the portions and combine them accordingly.
400 The default is to store the combined parts as a new message in the
401 current folder, although this can be changed using formatting
402 strings as discussed above. Thus, if someone has sent you a
403 message in several parts (such as the output from
405 you can easily reassemble them into a single message in the
411 msg part type/subtype size description
412 5 message/partial 47K part 1 of 4
413 6 message/partial 47K part 2 of 4
414 7 message/partial 47K part 3 of 4
415 8 message/partial 18K part 4 of 4
417 reassembling partials 5,6,7,8 to folder inbox as message 9
419 msg part type/subtype size description
420 9 application/octet-stream 118K
421 (extract with uncompress | tar xvpf -)
427 This will store exactly one message, containing the sum of the
428 parts. It doesn't matter whether the partials are specified in
431 will sort the partials, so that they are combined in the correct
434 can not locate every partial necessary to reassemble the message,
435 it will not store anything.
436 .SS "External Access"
437 For contents of type message/external-body,
438 \fImhstore\fR supports these access-types:
452 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
454 will look for the \*(lqnmh-access-ftp\*(rq
458 nmh-access-ftp: myftp.sh
461 to determine the pathname of a program to perform the FTP retrieval.
462 This program is invoked with these arguments:
466 domain name of FTP-site
472 \*(lqascii\*(rq or \*(lqbinary\*(rq
476 The program should terminate with an exit status of zero if the
477 retrieval is successful, and a non-zero exit status otherwise.
479 For the \*(lqurl\*(rq access types,
481 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
484 nmh-access-url: curl -L
487 to determine the program to use to perform the HTTP retrieval. This program
488 is invoked with one argument: the URL of the content to retrieve. The program
489 should write the content to standard out, and should terminate with a status
490 of zero if the retrieval is successful and a non-zero exit status otherwise.
491 .SS "The Content Cache"
494 encounters an external content containing a
495 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
496 depending on the caching behavior of
498 the content might be read from or written to a cache.
500 The caching behavior of
502 is controlled with the
506 switches, which define the policy for reading from, and writing to, the cache,
507 respectively. One of four policies may be
508 specified: \*(lqpublic\*(rq, indicating that
511 of a publicly-accessible content cache; \*(lqprivate\*(rq, indicating that
513 should make use of the user's private content cache;
514 \*(lqnever\*(rq, indicating that
516 should never make use of caching; and, \*(lqask\*(rq, indicating that
520 There are two directories where contents may be cached: the profile entry
521 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
522 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
523 private contents. The former should be an absolute (rooted) directory
532 might be used if you didn't care that the cache got wiped after each
533 reboot of the system. The latter is interpreted relative to the user's
534 nmh directory, if not rooted, e.g.,
537 nmh-private-cache: .cache
540 (which is the default value).
541 .SS "User Environment"
542 Because the environment in which
544 operates may vary for different machines,
546 will look for the environment variable MHSTORE .
547 If present, this specifies the name of an additional user profile
548 which should be read. Hence, when a user logs in on a particular
549 machine, this environment variable should be set to refer to a
550 file containing definitions useful for that machine. Finally,
552 will attempt to consult
555 %nmhetcdir%/mhn.defaults
558 which is created automatically during
562 See "Profile Lookup" in
564 for the profile search order, and for how duplicate entries are treated.
566 .SS Decoding RFC 2047-encoded file names
567 The improper RFC 2047 encoding of file name parameters can be replaced
568 with correct RFC 2231 encoding using
570 either permanently or ephemerally, e.g.,
574 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
580 is not necessary, though recommended to avoid silently overwriting an existing
584 looks for additional profile files in multiple locations: absolute
585 pathnames are accessed directly, tilde expansion is done on usernames,
586 and files are searched for in the user's
588 directory as specified in their profile. If not found there, the directory
589 .RI \*(lq %nmhetcdir% \*(rq
594 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
595 ^$HOME/.mh_profile~^The user profile
596 ^$MHSTORE~^Additional profile entries
597 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
599 .SH "PROFILE COMPONENTS"
603 .ta \w'ExtraBigProfileName 'u
604 ^Path:~^To determine the user's nmh directory
605 ^Current\-Folder:~^To find the default current folder
606 ^nmh-access-ftp:~^Program to retrieve contents via FTP
607 ^nmh-access-url:~^Program to retrieve contents via HTTP
608 ^nmh-cache~^Public directory to store cached external contents
609 ^nmh-private-cache~^Personal directory to store cached external contents
610 ^nmh-storage~^Directory to store contents
611 ^mhstore-store-<type>*~^Template for storing contents
621 .RB ` +folder "' defaults to the current folder"
622 .RB ` msgs "' defaults to cur"
624 .RB ` \-clobber\ always '
626 .RB ` \-rcache\ ask '
627 .RB ` \-wcache\ ask '
630 If a folder is given, it will become the current folder. The last
631 message selected will become the current message.
633 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob