1 .TH MHSTORE %manext1% "March 2, 2014" "%nmhversion%"
6 mhstore \- store contents of MIME messages into files
26 .RB [ \-auto " | " \-noauto ]
28 .IR always " | " auto " | " suffix " | " ask " | " never ]
33 .RB [ \-check " | " \-nocheck ]
34 .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
57 switches, you may limit the scope of
60 subparts (of a multipart content) and/or particular content types.
68 file as the source message, rather than a message from a folder.
69 If you specify this file as \*(lq-\*(rq, then
72 accept the source message on the standard input. Note that the
73 file, or input from standard input should be a validly formatted
74 message, just like any other
78 be in mail drop format (to convert a file in mail drop format to
84 A part specification consists of a series of numbers separated by
85 dots. For example, in a multipart content containing three parts,
86 these would be named as 1, 2, and 3, respectively. If part 2 was
87 also a multipart content containing two parts, these would be named
88 as 2.1 and 2.2, respectively. Note that the
91 effective for only messages containing a multipart content. If a
92 message has some other kind of content, or if the part is itself
93 another multipart content, the
95 switch will not prevent
96 the content from being acted upon.
98 A content specification consists of a content type and a subtype.
99 The initial list of \*(lqstandard\*(rq content types and subtypes
100 can be found in RFC 2046.
102 A list of commonly used contents is briefly reproduced here:
106 .ta \w'application 'u
110 multipart mixed, alternative, digest, parallel
111 message rfc822, partial, external-body
112 application octet-stream, postscript
119 A legal MIME message must contain a subtype specification.
121 To specify a content, regardless of its subtype, just use the name
122 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
123 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
124 Note that regardless of the values given to the
127 a multipart content (of any subtype listed above) is always acted
128 upon. Further note that if the
130 switch is used, and it is
131 desirable to act on a message/external-body content, then the
133 switch must be used twice: once for message/external-body
134 and once for the content externally referenced.
138 switch will alter the part ordering of multipart/alternative MIME sections
139 in order to override the sender-imposed default ordering.
142 switch is functionally most important for
144 but is also implemented in
148 to make common part number ordering possible across all three programs.
153 for more information on
155 .SS "Checking the Contents"
160 to check each content for
161 an integrity checksum. If a content has such a checksum (specified
162 as a Content-MD5 header field), then
165 verify the integrity of the content.
166 .SS "Storing the Contents"
168 will store the contents of the named messages in
169 \*(lqnative\*(rq (decoded) format. Two things must be determined:
170 the directory to store the content, and the filenames. Files are
171 written in the directory given by the \*(lqnmh-storage\*(rq profile
178 If this entry isn't present,
179 the current working directory is used.
183 switch is given, its argument is used for the filename to store all
184 of the content, with \*(lq-\*(rq indicating standard output. If the
186 switch is given, then
188 will check if the message contains information indicating the filename
189 that should be used to store the content. This information should be
190 specified as the \*(lqfilename\*(rq attribute in the
191 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
192 attribute in the \*(lqContent-Type\*(rq header for the content you are
193 storing. For security reasons, this filename will be ignored if it
194 begins with the character '/', '.', '|', or '!', or if it contains the
195 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
198 switch setting other than the default of \*(lqalways\*(rq to avoid
199 overwriting existing files.
203 switch is not given (or is being ignored for security
206 will look in the user's profile for a
207 \*(lqformatting string\*(rq to determine how the different contents
208 should be stored. First,
210 will look for an entry of
214 mhstore-store-<type>/<subtype>
217 to determine the formatting string. If this isn't found,
219 will look for an entry of the form:
225 to determine the formatting string.
227 If the formatting string starts with a \*(lq+\*(rq character, then
228 content is stored in the named folder. A formatting string consisting
229 solely of a \*(lq+\*(rq character is interpreted to be the current
232 If the formatting string consists solely of a \*(lq-\*(rq character,
233 then the content is sent to the standard output.
235 If the formatting string starts with a '|', then it represents
238 to execute which should
239 ultimately store the content. The content will be passed to the
240 standard input of the command. Before the command is executed,
242 will change to the appropriate directory, and any
243 escapes (given below) in the formatting string will be expanded.
244 The use of the \*(lq%a\*(rq sequence is not recommended because
245 the user has no control over the Content-Type parameter data.
247 Otherwise the formatting string will represent a pathname in which
248 to store the content. If the formatting string starts with a '/',
249 then the content will be stored in the full path given, else the
250 file name will be relative to the value of \*(lqnmh-storage\*(rq or
251 the current working directory. Any escapes (given below) will be
252 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
253 is not an absolute path, it will be relative to the folder that
254 contains the message(s).
256 A command or pathname formatting string may contain the following
257 escapes. If the content isn't part of a multipart (of any subtype
258 listed above) content, the p-escapes are ignored.
263 %a Parameters from Content-Type (only valid with command)
264 %m Insert message number
265 %P Insert part number with leading dot
266 %p Insert part number without leading dot
267 %t Insert content type
268 %s Insert content subtype
269 %% Insert character %
273 If no formatting string is found,
276 if the content is application/octet-stream with parameter
277 \*(lqtype=tar\*(rq. If so,
279 will choose an appropriate
280 filename. If the content is not application/octet-stream, then
282 will check to see if the content is a message. If
285 will use the value \*(lq+\*(rq. As a last resort,
287 will use the value \*(lq%m%P.%s\*(rq.
289 Example profile entries might be:
293 mhstore-store-text: %m%P.txt
294 mhstore-store-text: +inbox
295 mhstore-store-message/partial: +
296 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
297 mhstore-store-image/jpeg: %m%P.jpg
298 mhstore-store-application/PostScript: %m%P.ps
306 to print out the names of files that it stores. For backward
307 compatibility, it is the default. The
309 switch suppresses these printouts.
311 .SS "Overwriting Existing Files"
314 switch controls whether
316 should overwrite existing files. The allowed values for this switch
317 and corresponding behavior when
319 encounters an existing file are:
324 always Overwrite existing file (default)
325 auto Create new file of form name-n.extension
326 suffix Create new file of form name.extension.n
327 ask Prompt the user to specify whether or not to overwrite
329 never Do not overwrite existing file
338 is the lowest unused number, starting from one, in the same form. If
339 a filename does not have an extension (following a '.'), then
343 create a new file of the form
353 will be the number of files that were requested but not stored.
357 if standard input is connected to a terminal,
358 the user is prompted to respond
363 to whether the file should be overwritten. The responses
364 can be abbreviated. If the user responds with
368 prompts the user for the name of the new file to be created. If it is
369 a relative path name (does not begin with '/'), then it is relative to
370 the current directory. If it is an absolute or relative path to a
371 directory that does not exist, the user will be prompted whether to
372 create the directory. If standard input is not connected to a
377 .SS "Reassembling Messages of Type message/partial"
379 is also able to reassemble messages that have been
380 split into multiple messages of type \*(lqmessage/partial\*(rq.
382 When asked to store a content containing a partial message,
384 will try to locate all of the portions and combine
385 them accordingly. The default is to store the combined parts as
386 a new message in the current folder, although this can be changed
387 using formatting strings as discussed above. Thus, if someone has
388 sent you a message in several parts (such as the output from
390 you can easily reassemble them all into a single
391 message in the following fashion:
396 msg part type/subtype size description
397 5 message/partial 47K part 1 of 4
398 6 message/partial 47K part 2 of 4
399 7 message/partial 47K part 3 of 4
400 8 message/partial 18K part 4 of 4
402 reassembling partials 5,6,7,8 to folder inbox as message 9
404 msg part type/subtype size description
405 9 application/octet-stream 118K
406 (extract with uncompress | tar xvpf -)
412 This will store exactly one message, containing the sum of the
413 parts. It doesn't matter whether the partials are specified in
416 will sort the partials, so that they
417 are combined in the correct order. But if
420 locate every partial necessary to reassemble the message, it will
422 .SS "External Access"
423 For contents of type message/external-body,
424 \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 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,
494 and writing to, the cache, respectively. One of four policies may be
495 specified: \*(lqpublic\*(rq, indicating that
498 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
501 should make use of the user's private content cache;
502 \*(lqnever\*(rq, indicating that
504 should never make use of
505 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
536 will look for the environment variable
538 If present, this specifies the name of an additional
539 user profile which should be read. Hence, when a user logs in on a
540 particular machine, this environment variable should be set to
541 refer to a file containing definitions useful for that machine.
544 will attempt to consult
547 %nmhetcdir%/mhn.defaults
550 which is created automatically during
554 See "Profile Lookup" in
556 for the profile search order, and for how duplicate entries are treated.
559 looks for additional profile files in multiple locations: absolute
560 pathnames are accessed directly, tilde expansion is done on usernames,
561 and files are searched for in the user's
563 directory as specified in their profile. If not found there, the directory
564 .RI \*(lq %nmhetcdir% \*(rq
569 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
570 ^$HOME/\&.mh\(ruprofile~^The user profile
571 ^$MHSTORE~^Additional profile entries
572 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
574 .SH "PROFILE COMPONENTS"
578 .ta \w'ExtraBigProfileName 'u
579 ^Path:~^To determine the user's nmh directory
580 ^Current\-Folder:~^To find the default current folder
581 ^nmh-access-ftp:~^Program to retrieve contents via FTP
582 ^nmh-access-url:~^Program to retrieve contents via HTTP
583 ^nmh-cache~^Public directory to store cached external contents
584 ^nmh-private-cache~^Personal directory to store cached external contents
585 ^nmh-storage~^Directory to store contents
586 ^mhstore-store-<type>*~^Template for storing contents
595 .RB ` +folder "' defaults to the current folder"
596 .RB ` msgs "' defaults to cur"
598 .RB ` \-clobber\ always '
600 .RB ` \-rcache\ ask '
601 .RB ` \-wcache\ ask '
604 If a folder is given, it will become the current folder. The last
605 message selected will become the current message.
607 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob