-.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
-.\"
+.TH MHSTORE %manext1% 2015-02-06 "%nmhversion%"
+.
.\" %nmhwarning%
-.\"
+.
.SH NAME
-mhstore \- store contents of MIME messages into files
+mhstore \- store contents of nmh MIME messages into files
.SH SYNOPSIS
.HP 5
.na
.B mhstore
+.RB [ \-help ]
+.RB [ \-version ]
.RI [ +folder ]
.RI [ msgs ]
.RB [ \-file
.IR file ]
+.RB [ \-outfile
+.IR outfile ]
.RB [ \-part
.IR number ]
\&...
.RB [ \-type
.IR content ]
\&...
+.RB [ \-prefer
+.IR content ]
+\&...
+.RB [ \-noprefer ]
.RB [ \-auto " | " \-noauto ]
.RB [ \-clobber
.IR always " | " auto " | " suffix " | " ask " | " never ]
.RB [ \-wcache
.IR policy ]
.RB [ \-check " | " \-nocheck ]
-.RB [ \-version ]
-.RB [ \-help ]
+.RB [ \-verbose " | " \-noverbose ]
.ad
.SH DESCRIPTION
The
.B mhstore
-command allows you to store the contents of a
-collection of MIME (multi-media) messages into files or other
-messages.
+command allows you to store the contents of a collection of MIME
+(multi-media) messages into files or other messages.
.PP
.B mhstore
-manipulates multi-media messages as specified in
-RFC\-2045 thru RFC\-2049.
+manipulates multi-media messages as specified in RFC 2045 to RFC 2049.
.PP
By default,
.B mhstore
will store all the parts of each message.
-Each part will be store in a separate file. The header fields of
+Each part will be stored in a separate file. The header fields of
the message are not stored. By using the
-.B \-part
+.BR \-part ,
+.BR \-type ,
and
-.B \-type
-switches, you may limit the scope of
-.B mhstore
-to particular
-subparts (of a multipart content) and/or particular content types.
+.B \-prefer
+switches, you may limit and reorder the set of parts to be stored,
+based on part number and/or content type.
.PP
-The option
+The
.B \-file
.I file
-directs
+switch directs
.B mhstore
-to use the specified
-file as the source message, rather than a message from a folder.
-If you specify this file as \*(lq-\*(rq, then
+to use the specified file as the source message, rather than a message
+from a folder. If you specify this file as \*(lq-\*(rq, then
.B mhstore
-will
-accept the source message on the standard input. Note that the
-file, or input from standard input should be a validly formatted
+will accept the source message on the standard input. Note that the
+file, or input from standard input, should be a validly formatted
message, just like any other
.B nmh
message. It should
-.B NOT
-be in mail drop format (to convert a file in mail drop format to
-a folder of
+.I not
+be in mail drop format (to convert a file in
+mail drop format to a folder of
.B nmh
messages, see
-.BR inc (1)).
+.IR inc (1)).
.PP
A part specification consists of a series of numbers separated by
dots. For example, in a multipart content containing three parts,
-these would be named as 1, 2, and 3, respectively. If part 2 was
-also a multipart content containing two parts, these would be named
-as 2.1 and 2.2, respectively. Note that the
+these would be named as 1, 2, and 3, respectively. If part 2 was also
+a multipart content containing two parts, these would be named as 2.1
+and 2.2, respectively. Note that the
.B \-part
-switch is
-effective for only messages containing a multipart content. If a
-message has some other kind of content, or if the part is itself
+switch is effective only for messages containing a multipart content.
+If a message has some other kind of content, or if the part is itself
another multipart content, the
.B \-part
-switch will not prevent
-the content from being acted upon.
+switch will not prevent the content from being acted upon.
+.PP
+The
+.B \-type
+switch can also be used to restrict (or, when used in conjunction with
+.BR \-part ,
+to further restrict) the selection of parts according to content type.
+One or more
+.B \-type
+switches part will only select the first match from a
+multipart/alternative, even if there is more than one
+subpart that matches (one of) the given content type(s).
+.PP
+Using either
+.B \-part
+or
+.B -type
+switches alone will cause either to select the part(s) they match.
+Using them together will select only the part(s) matched by both
+(sets of) switches. In other words, the result is the intersection,
+and not the union, of their separate match results.
.PP
A content specification consists of a content type and a subtype.
-The initial list of \*(lqstandard\*(rq content types and subtypes
-can be found in RFC\-2046.
+The initial list of \*(lqstandard\*(rq content types and subtypes can
+be found in RFC 2046.
.PP
A list of commonly used contents is briefly reproduced here:
.PP
subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
Note that regardless of the values given to the
.B \-type
-switch,
-a multipart content (of any subtype listed above) is always acted
+switch, a multipart content (of any subtype listed above) is always acted
upon. Further note that if the
.B \-type
-switch is used, and it is
-desirable to act on a message/external-body content, then the
+switch is used, and it is desirable to act on a message/external-body
+content, then the
.B \-type
-switch must be used twice: once for message/external-body
-and once for the content externally referenced.
+switch must be used twice: once for message/external-body and once for
+the content externally referenced.
+.PP
+The
+.B \-prefer
+switch will alter the part-ordering of multipart/alternative MIME sections
+in order to override the sender-imposed default ordering.
+The
+.B \-prefer
+switch is functionally most important for
+.BR mhshow ,
+but is also implemented in
+.B mhlist
+and
+.B mhstore
+to make common part-numbering possible across all three programs.
+The last of multiple
+.B \-prefer
+switches will have the highest priority. This allows the command line
+switches to override profile entries.
+See
+.IR mhlist (1)
+and
+.IR mhshow (1)
+for more information on
+.BR \-prefer .
+.PP
+The
+.B \-noprefer
+switch will cancel any previous
+.B \-prefer
+switches.
.SS "Checking the Contents"
The
.B \-check
switch tells
.B mhstore
-to check each content for
-an integrity checksum. If a content has such a checksum (specified
-as a Content-MD5 header field), then
+to check each content for an integrity checksum.
+If a content has such a checksum (specified as a Content-MD5 header
+field), then
.B mhstore
-will attempt to
-verify the integrity of the content.
+will attempt to verify the integrity of the content.
.SS "Storing the Contents"
-The
.B mhstore
will store the contents of the named messages in
\*(lqnative\*(rq (decoded) format. Two things must be determined:
-the directory to store the content, and the filenames. Files are
-written in the directory given by the \*(lqnmh-storage\*(rq profile
-entry, e.g.,
+the directory in which to store the content, and the filenames.
+Files are written in the directory given by the
+\*(lqnmh-storage\*(rq profile entry, e.g.,
.PP
.RS 5
nmh-storage: /tmp
.RE
.PP
-If this entry isn't present,
-the current working directory is used.
+If this entry isn't present, the current working directory is used.
.PP
If the
+.B \-outfile
+switch is given, its argument is used for the filename to store all
+of the content, with \*(lq-\*(rq indicating standard output. If the
.B \-auto
switch is given, then
.B mhstore
-will check if
-the message contains information indicating the filename that should
-be used to store the content. This information should be specified
-as the attribute \*(lqname=filename\*(rq in the \*(lqContent-Type\*(rq header
-for the content you are storing. For security reasons, this filename
-will be ignored if it begins with the character '/', '.', '|', or '!',
-or if it contains the character '%'. For the sake of security,
-this switch is not the default, and it is recommended that you do
-NOT put the
-.B \-auto
-switch in your
-.I \&.mh\(ruprofile
-file.
+will check if the message contains information indicating the filename
+that should be used to store the content. This information should be
+specified as the \*(lqfilename\*(rq attribute in the
+\*(lqContent-Disposition\*(rq header or as the \*(lqname\*(rq
+attribute in the \*(lqContent-Type\*(rq header for the content you are
+storing. For security reasons, this filename will be ignored if it
+begins with the character '/', '.', '|', or '!', or if it contains the
+character '%'. We also recommend using a \*(lqnmh-storage\*(rq profile
+entry or a
+.B \-clobber
+switch setting other than the default of \*(lqalways\*(rq to avoid
+overwriting existing files.
.PP
If the
.B \-auto
-switch is not given (or is being ignored for security
-reasons) then
+switch is not given (or is being ignored for security reasons) then
.B mhstore
-will look in the user's profile for a
-\*(lqformatting string\*(rq to determine how the different contents
-should be stored. First,
+will look in the user's profile for a \*(lqformatting string\*(rq to
+determine how the different contents should be stored. First,
.B mhstore
-will look for an entry of
-the form:
+will look for an entry of the form:
.PP
.RS 5
mhstore-store-<type>/<subtype>
If the formatting string consists solely of a \*(lq-\*(rq character,
then the content is sent to the standard output.
.PP
-If the formatting string starts with a '|', then the display string
-will represent a command for
+If the formatting string starts with a '|', then it represents
+a command for
.B mhstore
-to execute which should
-ultimately store the content. The content will be passed to the
-standard input of the command. Before the command is executed,
+to execute which should ultimately store the content.
+The content will be passed to the standard input of the command.
+Before the command is executed,
.B mhstore
-will change to the appropriate directory, and any
-escapes (given below) in the display string will be expanded.
+will change to the appropriate directory, and any escapes (given below)
+in the formatting string will be expanded.
+The use of the \*(lq%a\*(rq sequence is not recommended because
+the user has no control over the Content-Type parameter data.
.PP
-Otherwise the formatting string will represent a pathname in which
+Otherwise, the formatting string will represent a pathname in which
to store the content. If the formatting string starts with a '/',
then the content will be stored in the full path given, else the
file name will be relative to the value of \*(lqnmh-storage\*(rq or
.RS 5
.nf
.ta \w'%P 'u
-%a Parameters from Content-type (only valid with command)
+%a Parameters from Content-Type (only valid with command)
%m Insert message number
%P Insert part number with leading dot
%p Insert part number without leading dot
.PP
If no formatting string is found,
.B mhstore
-will check to see
-if the content is application/octet-stream with parameter
+will check to see if the content is application/octet-stream with parameter
\*(lqtype=tar\*(rq. If so,
.B mhstore
-will choose an appropriate
-filename. If the content is not application/octet-stream, then
+will choose an appropriate filename. If the content is not
+application/octet-stream, then
.B mhstore
-will check to see if the content is a message. If
-so,
+will check to see if the content is a message. If so,
.B mhstore
will use the value \*(lq+\*(rq. As a last resort,
.B mhstore
.fi
.RE
.PP
+The
+.B \-verbose
+switch directs
+.B mhstore
+to print out the names of files that it stores. For backward
+compatibility, it is the default. The
+.B \-noverbose
+switch suppresses these printouts.
.SS "Overwriting Existing Files"
The
.B \-clobber
.PP
With
.IR ask ,
-if standard input is connected to a terminal,
-the user is prompted to respond
+if standard input is connected to a terminal, the user is prompted to
+respond
.IR yes ,
.IR no ,
or
-.I rename
+.IR rename ,
to whether the file should be overwritten. The responses
can be abbreviated. If the user responds with
.IR rename ,
.PP
When asked to store a content containing a partial message,
.B mhstore
-will try to locate all of the portions and combine
-them accordingly. The default is to store the combined parts as
-a new message in the current folder, although this can be changed
-using formatting strings as discussed above. Thus, if someone has
-sent you a message in several parts (such as the output from
+will try to locate all of the portions and combine them accordingly.
+The default is to store the combined parts as a new message in the
+current folder, although this can be changed using formatting
+strings as discussed above. Thus, if someone has sent you a
+message in several parts (such as the output from
.BR sendfiles ),
-you can easily reassemble them all into a single
-message in the following fashion:
+you can easily reassemble them into a single message in the
+following fashion:
.PP
.RS 5
.nf
parts. It doesn't matter whether the partials are specified in
order, since
.B mhstore
-will sort the partials, so that they
-are combined in the correct order. But if
+will sort the partials, so that they are combined in the correct
+order. But if
.B mhstore
-can not
-locate every partial necessary to reassemble the message, it will
-not store anything.
+can not locate every partial necessary to reassemble the message,
+it will not store anything.
.SS "External Access"
For contents of type message/external-body,
\fImhstore\fR supports these access-types:
-.PP
.IP \(bu 4
afs
.IP \(bu 4
local-file
.IP \(bu 4
mail-server
+.IP \(bu 4
+url
.PP
For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
.B mhstore
.PP
The program should terminate with an exit status of zero if the
retrieval is successful, and a non-zero exit status otherwise.
+.PP
+For the \*(lqurl\*(rq access types,
+.B mhstore
+will look for the \*(lqnmh-access-url\*(rq profile entry, e.g.,
+.PP
+.RS 5
+nmh-access-url: curl -L
+.RE
+.PP
+to determine the program to use to perform the HTTP retrieval. This program
+is invoked with one argument: the URL of the content to retrieve. The program
+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.
.SS "The Content Cache"
When
.B mhstore
.B \-rcache
and
.B \-wcache
-switches, which define the policy for reading from,
-and writing to, the cache, respectively. One of four policies may be
+switches, which define the policy for reading from, and writing to, the cache,
+respectively. One of four policies may be
specified: \*(lqpublic\*(rq, indicating that
.B mhstore
should make use
-of a publically-accessible content cache; \*(lqprivate\*(rq, indicating
-that
+of a publicly-accessible content cache; \*(lqprivate\*(rq, indicating that
.B mhstore
should make use of the user's private content cache;
\*(lqnever\*(rq, indicating that
.B mhstore
-should never make use of
-caching; and, \*(lqask\*(rq, indicating that
+should never make use of caching; and, \*(lqask\*(rq, indicating that
.B mhstore
should ask the user.
.PP
.PP
(which is the default value).
.SS "User Environment"
-Because the display environment in which
+Because the environment in which
.B mhstore
-operates may vary for
-different machines,
+operates may vary for different machines,
.B mhstore
-will look for the environment variable
-.BR $MHSTORE .
-If present, this specifies the name of an additional
-user profile which should be read. Hence, when a user logs in on a
-particular machine, this environment variable should be set to
-refer to a file containing definitions useful for that machine.
-Finally,
+will look for the environment variable MHSTORE .
+If present, this specifies the name of an additional user profile
+which should be read. Hence, when a user logs in on a particular
+machine, this environment variable should be set to refer to a
+file containing definitions useful for that machine. Finally,
.B mhstore
-will attempt to consult one other additional
-user profile, e.g.,
+will attempt to consult
.PP
.RS 5
-%etcdir%/mhn.defaults
+%nmhetcdir%/mhn.defaults
.RE
.PP
which is created automatically during
.B nmh
installation.
-
+.PP
+See "Profile Lookup" in
+.IR mh-profile (5)
+for the profile search order, and for how duplicate entries are treated.
+.SH EXAMPLES
+.SS Decoding RFC 2047-encoded file names
+The improper RFC 2047 encoding of file name parameters can be replaced
+with correct RFC 2231 encoding using
+.BR mhfixmsg ,
+either permanently or ephemerally, e.g.,
+.PP
+.RS
+.nf
+mhfixmsg -outfile - | mhstore -auto -clobber ask -file -
+.fi
+.RE
+.PP
+The
+.BI \-clobber ask
+is not necessary, though recommended to avoid silently overwriting an existing
+file.
.SH FILES
+.B mhstore
+looks for additional profile files in multiple locations: absolute
+pathnames are accessed directly, tilde expansion is done on usernames,
+and files are searched for in the user's
+.I Mail
+directory as specified in their profile. If not found there, the directory
+.RI \*(lq %nmhetcdir% \*(rq
+is checked.
+.PP
.fc ^ ~
.nf
-.ta \w'%etcdir%/ExtraBigFileName 'u
-^$HOME/\&.mh\(ruprofile~^The user profile
+.ta \w'%nmhetcdir%/ExtraBigFileName 'u
+^$HOME/.mh_profile~^The user profile
^$MHSTORE~^Additional profile entries
-^%etcdir%/mhn.defaults~^System default MIME profile entries
+^%nmhetcdir%/mhn.defaults~^System default MIME profile entries
.fi
-
.SH "PROFILE COMPONENTS"
.fc ^ ~
.nf
^Path:~^To determine the user's nmh directory
^Current\-Folder:~^To find the default current folder
^nmh-access-ftp:~^Program to retrieve contents via FTP
+^nmh-access-url:~^Program to retrieve contents via HTTP
^nmh-cache~^Public directory to store cached external contents
^nmh-private-cache~^Personal directory to store cached external contents
^nmh-storage~^Directory to store contents
^mhstore-store-<type>*~^Template for storing contents
.fi
-
.SH "SEE ALSO"
-mhbuild(1), mhlist(1), mhshow(1), sendfiles(1)
-
+.IR mhbuild (1),
+.IR mhfixmsg (1),
+.IR mhlist (1),
+.IR mhshow (1),
+.IR sendfiles (1)
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
.RB ` \-nocheck '
.RB ` \-rcache\ ask '
.RB ` \-wcache\ ask '
-
+.RB ` \-verbose '
.SH CONTEXT
If a folder is given, it will become the current folder. The last
message selected will become the current message.
-
.SH BUGS
Partial messages contained within a multipart content are not reassembled.
projects / nmh / blobdiff