1 .TH MHSTORE %manext1% "March 2, 2014" "%nmhversion%"
6 mhstore \- store contents of MIME messages into files
23 .RB [ \-auto " | " \-noauto ]
25 .IR always " | " auto " | " suffix " | " ask " | " never ]
30 .RB [ \-check " | " \-nocheck ]
31 .RB [ \-verbose " | " \-noverbose ]
38 command allows you to store the contents of a
39 collection of MIME (multi-media) messages into files or other
43 manipulates multi-media messages as specified in
48 will store all the parts of each message.
49 Each part will be store in a separate file. The header fields of
50 the message are not stored. By using the
54 switches, you may limit the scope of
57 subparts (of a multipart content) and/or particular content types.
65 file as the source message, rather than a message from a folder.
66 If you specify this file as \*(lq-\*(rq, then
69 accept the source message on the standard input. Note that the
70 file, or input from standard input should be a validly formatted
71 message, just like any other
75 be in mail drop format (to convert a file in mail drop format to
81 A part specification consists of a series of numbers separated by
82 dots. For example, in a multipart content containing three parts,
83 these would be named as 1, 2, and 3, respectively. If part 2 was
84 also a multipart content containing two parts, these would be named
85 as 2.1 and 2.2, respectively. Note that the
88 effective for only messages containing a multipart content. If a
89 message has some other kind of content, or if the part is itself
90 another multipart content, the
92 switch will not prevent
93 the content from being acted upon.
95 A content specification consists of a content type and a subtype.
96 The initial list of \*(lqstandard\*(rq content types and subtypes
97 can be found in RFC 2046.
99 A list of commonly used contents is briefly reproduced here:
103 .ta \w'application 'u
107 multipart mixed, alternative, digest, parallel
108 message rfc822, partial, external-body
109 application octet-stream, postscript
116 A legal MIME message must contain a subtype specification.
118 To specify a content, regardless of its subtype, just use the name
119 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
120 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
121 Note that regardless of the values given to the
124 a multipart content (of any subtype listed above) is always acted
125 upon. Further note that if the
127 switch is used, and it is
128 desirable to act on a message/external-body content, then the
130 switch must be used twice: once for message/external-body
131 and once for the content externally referenced.
132 .SS "Checking the Contents"
137 to check each content for
138 an integrity checksum. If a content has such a checksum (specified
139 as a Content-MD5 header field), then
142 verify the integrity of the content.
143 .SS "Storing the Contents"
146 will store the contents of the named messages in
147 \*(lqnative\*(rq (decoded) format. Two things must be determined:
148 the directory to store the content, and the filenames. Files are
149 written in the directory given by the \*(lqnmh-storage\*(rq profile
156 If this entry isn't present,
157 the current working directory is used.
161 switch is given, its argument is used for the filename to store all
162 of the content, with \*(lq-\*(rq indicating standard output. If the
164 switch is given, then
166 will check if the message contains information indicating the filename
167 that should be used to store the content. This information should be
168 specified as the \*(lqfilename\*(rq attribute in the
169 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
170 attribute in the \*(lqContent-Type\*(rq header for the content you are
171 storing. For security reasons, this filename will be ignored if it
172 begins with the character '/', '.', '|', or '!', or if it contains the
173 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
176 switch setting other than the default of \*(lqalways\*(rq to avoid
177 overwriting existing files.
181 switch is not given (or is being ignored for security
184 will look in the user's profile for a
185 \*(lqformatting string\*(rq to determine how the different contents
186 should be stored. First,
188 will look for an entry of
192 mhstore-store-<type>/<subtype>
195 to determine the formatting string. If this isn't found,
197 will look for an entry of the form:
203 to determine the formatting string.
205 If the formatting string starts with a \*(lq+\*(rq character, then
206 content is stored in the named folder. A formatting string consisting
207 solely of a \*(lq+\*(rq character is interpreted to be the current
210 If the formatting string consists solely of a \*(lq-\*(rq character,
211 then the content is sent to the standard output.
213 If the formatting string starts with a '|', then it represents
216 to execute which should
217 ultimately store the content. The content will be passed to the
218 standard input of the command. Before the command is executed,
220 will change to the appropriate directory, and any
221 escapes (given below) in the formatting string will be expanded.
222 The use of the \*(lq%a\*(rq sequence is not recommended because
223 the user has no control over the Content-Type parameter data.
225 Otherwise the formatting string will represent a pathname in which
226 to store the content. If the formatting string starts with a '/',
227 then the content will be stored in the full path given, else the
228 file name will be relative to the value of \*(lqnmh-storage\*(rq or
229 the current working directory. Any escapes (given below) will be
230 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
231 is not an absolute path, it will be relative to the folder that
232 contains the message(s).
234 A command or pathname formatting string may contain the following
235 escapes. If the content isn't part of a multipart (of any subtype
236 listed above) content, the p-escapes are ignored.
241 %a Parameters from Content-Type (only valid with command)
242 %m Insert message number
243 %P Insert part number with leading dot
244 %p Insert part number without leading dot
245 %t Insert content type
246 %s Insert content subtype
247 %% Insert character %
251 If no formatting string is found,
254 if the content is application/octet-stream with parameter
255 \*(lqtype=tar\*(rq. If so,
257 will choose an appropriate
258 filename. If the content is not application/octet-stream, then
260 will check to see if the content is a message. If
263 will use the value \*(lq+\*(rq. As a last resort,
265 will use the value \*(lq%m%P.%s\*(rq.
267 Example profile entries might be:
271 mhstore-store-text: %m%P.txt
272 mhstore-store-text: +inbox
273 mhstore-store-message/partial: +
274 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
275 mhstore-store-image/jpeg: %m%P.jpg
276 mhstore-store-application/PostScript: %m%P.ps
284 to print out the names of files that it stores. For backward
285 compatibility, it is the default. The
287 switch suppresses these printouts.
289 .SS "Overwriting Existing Files"
292 switch controls whether
294 should overwrite existing files. The allowed values for this switch
295 and corresponding behavior when
297 encounters an existing file are:
302 always Overwrite existing file (default)
303 auto Create new file of form name-n.extension
304 suffix Create new file of form name.extension.n
305 ask Prompt the user to specify whether or not to overwrite
307 never Do not overwrite existing file
316 is the lowest unused number, starting from one, in the same form. If
317 a filename does not have an extension (following a '.'), then
321 create a new file of the form
331 will be the number of files that were requested but not stored.
335 if standard input is connected to a terminal,
336 the user is prompted to respond
341 to whether the file should be overwritten. The responses
342 can be abbreviated. If the user responds with
346 prompts the user for the name of the new file to be created. If it is
347 a relative path name (does not begin with '/'), then it is relative to
348 the current directory. If it is an absolute or relative path to a
349 directory that does not exist, the user will be prompted whether to
350 create the directory. If standard input is not connected to a
355 .SS "Reassembling Messages of Type message/partial"
357 is also able to reassemble messages that have been
358 split into multiple messages of type \*(lqmessage/partial\*(rq.
360 When asked to store a content containing a partial message,
362 will try to locate all of the portions and combine
363 them accordingly. The default is to store the combined parts as
364 a new message in the current folder, although this can be changed
365 using formatting strings as discussed above. Thus, if someone has
366 sent you a message in several parts (such as the output from
368 you can easily reassemble them all into a single
369 message in the following fashion:
374 msg part type/subtype size description
375 5 message/partial 47K part 1 of 4
376 6 message/partial 47K part 2 of 4
377 7 message/partial 47K part 3 of 4
378 8 message/partial 18K part 4 of 4
380 reassembling partials 5,6,7,8 to folder inbox as message 9
382 msg part type/subtype size description
383 9 application/octet-stream 118K
384 (extract with uncompress | tar xvpf -)
390 This will store exactly one message, containing the sum of the
391 parts. It doesn't matter whether the partials are specified in
394 will sort the partials, so that they
395 are combined in the correct order. But if
398 locate every partial necessary to reassemble the message, it will
400 .SS "External Access"
401 For contents of type message/external-body,
402 \fImhstore\fR supports these access-types:
417 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
419 will look for the \*(lqnmh-access-ftp\*(rq
423 nmh-access-ftp: myftp.sh
426 to determine the pathname of a program to perform the FTP retrieval.
427 This program is invoked with these arguments:
431 domain name of FTP-site
437 \*(lqascii\*(rq or \*(lqbinary\*(rq
441 The program should terminate with an exit status of zero if the
442 retrieval is successful, and a non-zero exit status otherwise.
444 For the \*(lqurl\*(rq access types,
446 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
449 nmh-access-url: curl -L
452 to determine the program to use to perform the HTTP retrieval. This program
453 is invoked with one argument: the URL of the content to retrieve. The program
454 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.
456 .SS "The Content Cache"
459 encounters an external content containing a
460 \*(lqContent-ID:\*(rq field, and if the content allows caching, then
461 depending on the caching behavior of
463 the content might be read from or written to a cache.
465 The caching behavior of
467 is controlled with the
471 switches, which define the policy for reading from,
472 and writing to, the cache, respectively. One of four policies may be
473 specified: \*(lqpublic\*(rq, indicating that
476 of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
479 should make use of the user's private content cache;
480 \*(lqnever\*(rq, indicating that
482 should never make use of
483 caching; and, \*(lqask\*(rq, indicating that
487 There are two directories where contents may be cached: the profile entry
488 \*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
489 the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
490 private contents. The former should be an absolute (rooted) directory
499 might be used if you didn't care that the cache got wiped after each
500 reboot of the system. The latter is interpreted relative to the user's
501 nmh directory, if not rooted, e.g.,
504 nmh-private-cache: .cache
507 (which is the default value).
508 .SS "User Environment"
509 Because the environment in which
511 operates may vary for
514 will look for the environment variable
516 If present, this specifies the name of an additional
517 user profile which should be read. Hence, when a user logs in on a
518 particular machine, this environment variable should be set to
519 refer to a file containing definitions useful for that machine.
522 will attempt to consult
525 %etcdir%/mhn.defaults
528 which is created automatically during
532 See "Profile Lookup" in
534 for the profile search order, and for how duplicate entries are treated.
537 looks for additional profile files in multiple locations: absolute
538 pathnames are accessed directly, tilde expansion is done on usernames,
539 and files are searched for in the user's
541 directory as specified in their profile. If not found there, the directory
542 .RI \*(lq %etcdir% \*(rq
547 .ta \w'%etcdir%/ExtraBigFileName 'u
548 ^$HOME/\&.mh\(ruprofile~^The user profile
549 ^$MHSTORE~^Additional profile entries
550 ^%etcdir%/mhn.defaults~^System default MIME profile entries
552 .SH "PROFILE COMPONENTS"
556 .ta \w'ExtraBigProfileName 'u
557 ^Path:~^To determine the user's nmh directory
558 ^Current\-Folder:~^To find the default current folder
559 ^nmh-access-ftp:~^Program to retrieve contents via FTP
560 ^nmh-access-url:~^Program to retrieve contents via HTTP
561 ^nmh-cache~^Public directory to store cached external contents
562 ^nmh-private-cache~^Personal directory to store cached external contents
563 ^nmh-storage~^Directory to store contents
564 ^mhstore-store-<type>*~^Template for storing contents
573 .RB ` +folder "' defaults to the current folder"
574 .RB ` msgs "' defaults to cur"
576 .RB ` \-clobber\ always '
578 .RB ` \-rcache\ ask '
579 .RB ` \-wcache\ ask '
582 If a folder is given, it will become the current folder. The last
583 message selected will become the current message.
585 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob