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.
165 for more information on
167 .SS "Checking the Contents"
172 to check each content for an integrity checksum.
173 If a content has such a checksum (specified as a Content-MD5 header
176 will attempt to verify the integrity of the content.
177 .SS "Storing the Contents"
179 will store the contents of the named messages in
180 \*(lqnative\*(rq (decoded) format. Two things must be determined:
181 the directory in which to store the content, and the filenames.
182 Files are written in the directory given by the
183 \*(lqnmh-storage\*(rq profile entry, e.g.,
189 If this entry isn't present, the current working directory is used.
193 switch is given, its argument is used for the filename to store all
194 of the content, with \*(lq-\*(rq indicating standard output. If the
196 switch is given, then
198 will check if the message contains information indicating the filename
199 that should be used to store the content. This information should be
200 specified as the \*(lqfilename\*(rq attribute in the
201 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
202 attribute in the \*(lqContent-Type\*(rq header for the content you are
203 storing. For security reasons, this filename will be ignored if it
204 begins with the character '/', '.', '|', or '!', or if it contains the
205 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
208 switch setting other than the default of \*(lqalways\*(rq to avoid
209 overwriting existing files.
213 switch is not given (or is being ignored for security reasons) then
215 will look in the user's profile for a \*(lqformatting string\*(rq to
216 determine how the different contents should be stored. First,
218 will look for an entry of the form:
221 mhstore-store-<type>/<subtype>
224 to determine the formatting string. If this isn't found,
226 will look for an entry of the form:
232 to determine the formatting string.
234 If the formatting string starts with a \*(lq+\*(rq character, then
235 content is stored in the named folder. A formatting string consisting
236 solely of a \*(lq+\*(rq character is interpreted to be the current
239 If the formatting string consists solely of a \*(lq-\*(rq character,
240 then the content is sent to the standard output.
242 If the formatting string starts with a '|', then it represents
245 to execute which should ultimately store the content.
246 The content will be passed to the standard input of the command.
247 Before the command is executed,
249 will change to the appropriate directory, and any escapes (given below)
250 in the formatting string will be expanded.
251 The use of the \*(lq%a\*(rq sequence is not recommended because
252 the user has no control over the Content-Type parameter data.
254 Otherwise, the formatting string will represent a pathname in which
255 to store the content. If the formatting string starts with a '/',
256 then the content will be stored in the full path given, else the
257 file name will be relative to the value of \*(lqnmh-storage\*(rq or
258 the current working directory. Any escapes (given below) will be
259 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
260 is not an absolute path, it will be relative to the folder that
261 contains the message(s).
263 A command or pathname formatting string may contain the following
264 escapes. If the content isn't part of a multipart (of any subtype
265 listed above) content, the p-escapes are ignored.
270 %a Parameters from Content-Type (only valid with command)
271 %m Insert message number
272 %P Insert part number with leading dot
273 %p Insert part number without leading dot
274 %t Insert content type
275 %s Insert content subtype
276 %% Insert character %
280 If no formatting string is found,
282 will check to see if the content is application/octet-stream with parameter
283 \*(lqtype=tar\*(rq. If so,
285 will choose an appropriate filename. If the content is not
286 application/octet-stream, then
288 will check to see if the content is a message. If so,
290 will use the value \*(lq+\*(rq. As a last resort,
292 will use the value \*(lq%m%P.%s\*(rq.
294 Example profile entries might be:
298 mhstore-store-text: %m%P.txt
299 mhstore-store-text: +inbox
300 mhstore-store-message/partial: +
301 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
302 mhstore-store-image/jpeg: %m%P.jpg
303 mhstore-store-application/PostScript: %m%P.ps
311 to print out the names of files that it stores. For backward
312 compatibility, it is the default. The
314 switch suppresses these printouts.
315 .SS "Overwriting Existing Files"
318 switch controls whether
320 should overwrite existing files. The allowed values for this switch
321 and corresponding behavior when
323 encounters an existing file are:
328 always Overwrite existing file (default)
329 auto Create new file of form name-n.extension
330 suffix Create new file of form name.extension.n
331 ask Prompt the user to specify whether or not to overwrite
333 never Do not overwrite existing file
342 is the lowest unused number, starting from one, in the same form. If
343 a filename does not have an extension (following a '.'), then
347 create a new file of the form
357 will be the number of files that were requested but not stored.
361 if standard input is connected to a terminal, the user is prompted to
367 to whether the file should be overwritten. The responses
368 can be abbreviated. If the user responds with
372 prompts the user for the name of the new file to be created. If it is
373 a relative path name (does not begin with '/'), then it is relative to
374 the current directory. If it is an absolute or relative path to a
375 directory that does not exist, the user will be prompted whether to
376 create the directory. If standard input is not connected to a
381 .SS "Reassembling Messages of Type message/partial"
383 is also able to reassemble messages that have been
384 split into multiple messages of type \*(lqmessage/partial\*(rq.
386 When asked to store a content containing a partial message,
388 will try to locate all of the portions and combine them accordingly.
389 The default is to store the combined parts as a new message in the
390 current folder, although this can be changed using formatting
391 strings as discussed above. Thus, if someone has sent you a
392 message in several parts (such as the output from
394 you can easily reassemble them into a single message in the
400 msg part type/subtype size description
401 5 message/partial 47K part 1 of 4
402 6 message/partial 47K part 2 of 4
403 7 message/partial 47K part 3 of 4
404 8 message/partial 18K part 4 of 4
406 reassembling partials 5,6,7,8 to folder inbox as message 9
408 msg part type/subtype size description
409 9 application/octet-stream 118K
410 (extract with uncompress | tar xvpf -)
416 This will store exactly one message, containing the sum of the
417 parts. It doesn't matter whether the partials are specified in
420 will sort the partials, so that they are combined in the correct
423 can not locate every partial necessary to reassemble the message,
424 it will not store anything.
425 .SS "External Access"
426 For contents of type message/external-body,
427 \fImhstore\fR supports these access-types:
441 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
443 will look for the \*(lqnmh-access-ftp\*(rq
447 nmh-access-ftp: myftp.sh
450 to determine the pathname of a program to perform the FTP retrieval.
451 This program is invoked with these arguments:
455 domain name of FTP-site
461 \*(lqascii\*(rq or \*(lqbinary\*(rq
465 The program should terminate with an exit status of zero if the
466 retrieval is successful, and a non-zero exit status otherwise.
468 For the \*(lqurl\*(rq access types,
470 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
473 nmh-access-url: curl -L
476 to determine the program to use to perform the HTTP retrieval. This program
477 is invoked with one argument: the URL of the content to retrieve. The program
478 should write the content to standard out, and should terminate with a status
479 of zero if the retrieval is successful and a non-zero exit status otherwise.
480 .SS "The Content Cache"
483 encounters an external content containing a
484 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
485 depending on the caching behavior of
487 the content might be read from or written to a cache.
489 The caching behavior of
491 is controlled with the
495 switches, which define the policy for reading from, and writing to, the cache,
496 respectively. One of four policies may be
497 specified: \*(lqpublic\*(rq, indicating that
500 of a publicly-accessible content cache; \*(lqprivate\*(rq, indicating that
502 should make use of the user's private content cache;
503 \*(lqnever\*(rq, indicating that
505 should never make use of caching; and, \*(lqask\*(rq, indicating that
509 There are two directories where contents may be cached: the profile entry
510 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
511 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
512 private contents. The former should be an absolute (rooted) directory
521 might be used if you didn't care that the cache got wiped after each
522 reboot of the system. The latter is interpreted relative to the user's
523 nmh directory, if not rooted, e.g.,
526 nmh-private-cache: .cache
529 (which is the default value).
530 .SS "User Environment"
531 Because the environment in which
533 operates may vary for different machines,
535 will look for the environment variable MHSTORE .
536 If present, this specifies the name of an additional user profile
537 which should be read. Hence, when a user logs in on a particular
538 machine, this environment variable should be set to refer to a
539 file containing definitions useful for that machine. Finally,
541 will attempt to consult
544 %nmhetcdir%/mhn.defaults
547 which is created automatically during
551 See "Profile Lookup" in
553 for the profile search order, and for how duplicate entries are treated.
555 .SS Decoding RFC 2047-encoded file names
556 The improper RFC 2047 encoding of file name parameters can be replaced
557 with correct RFC 2231 encoding using
559 either permanently or ephemerally, e.g.,
563 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
569 is not necessary, though recommended to avoid silently overwriting an existing
573 looks for additional profile files in multiple locations: absolute
574 pathnames are accessed directly, tilde expansion is done on usernames,
575 and files are searched for in the user's
577 directory as specified in their profile. If not found there, the directory
578 .RI \*(lq %nmhetcdir% \*(rq
583 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
584 ^$HOME/.mh_profile~^The user profile
585 ^$MHSTORE~^Additional profile entries
586 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
588 .SH "PROFILE COMPONENTS"
592 .ta \w'ExtraBigProfileName 'u
593 ^Path:~^To determine the user's nmh directory
594 ^Current\-Folder:~^To find the default current folder
595 ^nmh-access-ftp:~^Program to retrieve contents via FTP
596 ^nmh-access-url:~^Program to retrieve contents via HTTP
597 ^nmh-cache~^Public directory to store cached external contents
598 ^nmh-private-cache~^Personal directory to store cached external contents
599 ^nmh-storage~^Directory to store contents
600 ^mhstore-store-<type>*~^Template for storing contents
610 .RB ` +folder "' defaults to the current folder"
611 .RB ` msgs "' defaults to cur"
613 .RB ` \-clobber\ always '
615 .RB ` \-rcache\ ask '
616 .RB ` \-wcache\ ask '
619 If a folder is given, it will become the current folder. The last
620 message selected will become the current message.
622 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob