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 ]
32 .RB [ \-verbose " | " \-noverbose ]
37 command allows you to store the contents of a collection of MIME
38 (multi-media) messages into files or other messages.
41 manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
45 will store all the parts of each message.
46 Each part will be stored in a separate file. The header fields of
47 the message are not stored. By using the
52 switches, you may limit and reorder the set of parts to be stored,
53 based on part number and/or content type.
60 to use the specified file as the source message, rather than a message
61 from a folder. If you specify this file as \*(lq-\*(rq, then
63 will accept the source message on the standard input. Note that the
64 file, or input from standard input, should be a validly formatted
65 message, just like any other
69 be in mail drop format (to convert a file in
70 mail drop format to a folder of
75 A part specification consists of a series of numbers separated by
76 dots. For example, in a multipart content containing three parts,
77 these would be named as 1, 2, and 3, respectively. If part 2 was also
78 a multipart content containing two parts, these would be named as 2.1
79 and 2.2, respectively. Note that the
81 switch is effective only for messages containing a multipart content.
82 If a message has some other kind of content, or if the part is itself
83 another multipart content, the
85 switch will not prevent the content from being acted upon.
89 switch can also be used to restrict (or, when used in conjunction with
91 to further restrict) the selection of parts according to content type.
94 switches part will only select the first match from a
95 multipart/alternative, even if there is more than one
96 subpart that matches (one of) the given content type(s).
102 switches alone will cause either to select the part(s) they match.
103 Using them together will select only the part(s) matched by both
104 (sets of) switches. In other words, the result is the intersection,
105 and not the union, of their separate match results.
107 A content specification consists of a content type and a subtype.
108 The initial list of \*(lqstandard\*(rq content types and subtypes can
109 be found in RFC 2046.
111 A list of commonly used contents is briefly reproduced here:
115 .ta \w'application 'u
119 multipart mixed, alternative, digest, parallel
120 message rfc822, partial, external-body
121 application octet-stream, postscript
128 A legal MIME message must contain a subtype specification.
130 To specify a content, regardless of its subtype, just use the name
131 of the content, e.g., \*(lqaudio\*(rq. To specify a specific
132 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
133 Note that regardless of the values given to the
135 switch, a multipart content (of any subtype listed above) is always acted
136 upon. Further note that if the
138 switch is used, and it is desirable to act on a message/external-body
141 switch must be used twice: once for message/external-body and once for
142 the content externally referenced.
146 switch will alter the part-ordering of multipart/alternative MIME sections
147 in order to override the sender-imposed default ordering.
150 switch is functionally most important for
152 but is also implemented in
156 to make common part-numbering possible across all three programs.
159 switches will have the highest priority. This allows the command line
160 switches to override profile entries.
165 for more information on
170 switch will cancel any previous
173 .SS "Storing the Contents"
175 will store the contents of the named messages in
176 \*(lqnative\*(rq (decoded) format. Two things must be determined:
177 the directory in which to store the content, and the filenames.
178 Files are written in the directory given by the
179 \*(lqnmh-storage\*(rq profile entry, e.g.,
185 If this entry isn't present, the current working directory is used.
189 switch is given, its argument is used for the filename to store all
190 of the content, with \*(lq-\*(rq indicating standard output. If the
192 switch is given, then
194 will check if the message contains information indicating the filename
195 that should be used to store the content. This information should be
196 specified as the \*(lqfilename\*(rq attribute in the
197 \*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
198 attribute in the \*(lqContent-Type\*(rq header for the content you are
199 storing. For security reasons, this filename will be ignored if it
200 begins with the character '/', '.', '|', or '!', or if it contains the
201 character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
204 switch setting other than the default of \*(lqalways\*(rq to avoid
205 overwriting existing files.
209 switch is not given (or is being ignored for security reasons) then
211 will look in the user's profile for a \*(lqformatting string\*(rq to
212 determine how the different contents should be stored. First,
214 will look for an entry of the form:
217 mhstore-store-<type>/<subtype>
220 to determine the formatting string. If this isn't found,
222 will look for an entry of the form:
228 to determine the formatting string.
230 If the formatting string starts with a \*(lq+\*(rq character, then
231 content is stored in the named folder. A formatting string consisting
232 solely of a \*(lq+\*(rq character is interpreted to be the current
235 If the formatting string consists solely of a \*(lq-\*(rq character,
236 then the content is sent to the standard output.
238 If the formatting string starts with a '|', then it represents
241 to execute which should ultimately store the content.
242 The content will be passed to the standard input of the command.
243 Before the command is executed,
245 will change to the appropriate directory, and any escapes (given below)
246 in the formatting string will be expanded.
247 The use of the \*(lq%a\*(rq sequence is not recommended because
248 the user has no control over the Content-Type parameter data.
250 Otherwise, the formatting string will represent a pathname in which
251 to store the content. If the formatting string starts with a '/',
252 then the content will be stored in the full path given, else the
253 file name will be relative to the value of \*(lqnmh-storage\*(rq or
254 the current working directory. Any escapes (given below) will be
255 expanded, except for the a-escape. Note that if \*(lqnmh-storage\*(rq
256 is not an absolute path, it will be relative to the folder that
257 contains the message(s).
259 A command or pathname formatting string may contain the following
260 escapes. If the content isn't part of a multipart (of any subtype
261 listed above) content, the p-escapes are ignored.
266 %a Parameters from Content-Type (only valid with command)
267 %m Insert message number
268 %P Insert part number with leading dot
269 %p Insert part number without leading dot
270 %t Insert content type
271 %s Insert content subtype
272 %% Insert character %
276 If no formatting string is found,
278 will check to see if the content is application/octet-stream with parameter
279 \*(lqtype=tar\*(rq. If so,
281 will choose an appropriate filename. If the content is not
282 application/octet-stream, then
284 will check to see if the content is a message. If so,
286 will use the value \*(lq+\*(rq. As a last resort,
288 will use the value \*(lq%m%P.%s\*(rq.
290 Example profile entries might be:
294 mhstore-store-text: %m%P.txt
295 mhstore-store-text: +inbox
296 mhstore-store-message/partial: +
297 mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
298 mhstore-store-image/jpeg: %m%P.jpg
299 mhstore-store-application/PostScript: %m%P.ps
307 to print out the names of files that it stores. For backward
308 compatibility, it is the default. The
310 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, the user is prompted to
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 them accordingly.
385 The default is to store the combined parts as a new message in the
386 current folder, although this can be changed using formatting
387 strings as discussed above. Thus, if someone has sent you a
388 message in several parts (such as the output from
390 you can easily reassemble them into a single message in the
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 are combined in the correct
419 can not locate every partial necessary to reassemble the message,
420 it will not store anything.
421 .SS "External Access"
422 For contents of type message/external-body,
423 \fImhstore\fR supports these access-types:
437 For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
439 will look for the \*(lqnmh-access-ftp\*(rq
443 nmh-access-ftp: myftp.sh
446 to determine the pathname of a program to perform the FTP retrieval.
447 This program is invoked with these arguments:
451 domain name of FTP-site
457 \*(lqascii\*(rq or \*(lqbinary\*(rq
461 The program should terminate with an exit status of zero if the
462 retrieval is successful, and a non-zero exit status otherwise.
464 For the \*(lqurl\*(rq access types,
466 will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
469 nmh-access-url: curl -L
472 to determine the program to use to perform the HTTP retrieval. This program
473 is invoked with one argument: the URL of the content to retrieve. The program
474 should write the content to standard out, and should terminate with a status
475 of zero if the retrieval is successful and a non-zero exit status otherwise.
476 .SS "User Environment"
477 Because the environment in which
479 operates may vary for different machines,
481 will look for the environment variable MHSTORE .
482 If present, this specifies the name of an additional user profile
483 which should be read. Hence, when a user logs in on a particular
484 machine, this environment variable should be set to refer to a
485 file containing definitions useful for that machine. Finally,
487 will attempt to consult
490 %nmhetcdir%/mhn.defaults
493 which is created automatically during
497 See "Profile Lookup" in
499 for the profile search order, and for how duplicate entries are treated.
501 .SS Decoding RFC 2047-encoded file names
502 The improper RFC 2047 encoding of file name parameters can be replaced
503 with correct RFC 2231 encoding using
505 either permanently or ephemerally, e.g.,
509 mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
515 is not necessary, though recommended to avoid silently overwriting an existing
519 looks for additional profile files in multiple locations: absolute
520 pathnames are accessed directly, tilde expansion is done on usernames,
521 and files are searched for in the user's
523 directory as specified in their profile. If not found there, the directory
524 .RI \*(lq %nmhetcdir% \*(rq
529 .ta \w'%nmhetcdir%/ExtraBigFileName 'u
530 ^$HOME/.mh_profile~^The user profile
531 ^$MHSTORE~^Additional profile entries
532 ^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
534 .SH "PROFILE COMPONENTS"
538 .ta \w'ExtraBigProfileName 'u
539 ^Path:~^To determine the user's nmh directory
540 ^Current\-Folder:~^To find the default current folder
541 ^nmh-access-ftp:~^Program to retrieve contents via FTP
542 ^nmh-access-url:~^Program to retrieve contents via HTTP
543 ^nmh-storage~^Directory to store contents
544 ^mhstore-store-<type>*~^Template for storing contents
554 .RB ` +folder "' defaults to the current folder"
555 .RB ` msgs "' defaults to cur"
557 .RB ` \-clobber\ always '
561 If a folder is given, it will become the current folder. The last
562 message selected will become the current message.
564 Partial messages contained within a multipart content are not reassembled.
projects / nmh / blob