+.TH MHSTORE %manext1% "March 21, 2013" "%nmhversion%"
.\"
.\" %nmhwarning%
.\"
-.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
.SH NAME
mhstore \- store contents of MIME messages into files
.SH SYNOPSIS
.RI [ msgs ]
.RB [ \-file
.IR file ]
+.RB [ \-outfile
+.IR outfile ]
.RB [ \-part
.IR number ]
\&...
.IR content ]
\&...
.RB [ \-auto " | " \-noauto ]
+.RB [ \-clobber
+.IR always " | " auto " | " suffix " | " ask " | " never ]
.RB [ \-rcache
.IR policy ]
.RB [ \-wcache
.PP
.B mhstore
manipulates multi-media messages as specified in
-RFC\-2045 thru RFC\-2049.
+RFC 2045 to RFC 2049.
.PP
By default,
.B mhstore
to particular
subparts (of a multipart content) and/or particular content types.
.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.
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,
.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.
+can be found in RFC 2046.
.PP
A list of commonly used contents is briefly reproduced here:
.PP
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
+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 '%'. 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
.fi
.RE
.PP
+.SS "Overwriting Existing Files"
+The
+.B \-clobber
+switch controls whether
+.B mhstore
+should overwrite existing files. The allowed values for this switch
+and corresponding behavior when
+.B mhstore
+encounters an existing file are:
+.PP
+.RS 5
+.nf
+.ta \w'suffix 'u
+always Overwrite existing file (default)
+auto Create new file of form name-n.extension
+suffix Create new file of form name.extension.n
+ask Prompt the user to specify whether or not to overwrite
+ the existing file
+never Do not overwrite existing file
+.fi
+.RE
+.PP
+With
+.I auto
+and
+.IR suffix ,
+.I n
+is the lowest unused number, starting from one, in the same form. If
+a filename does not have an extension (following a '.'), then
+.I auto
+and
+.I suffix
+create a new file of the form
+.I name-n
+and
+.IR name.n ,
+respectively. With
+.I never
+and
+.IR ask ,
+the exit status of
+.B mhstore
+will be the number of files that were requested but not stored.
+.PP
+With
+.IR ask ,
+if standard input is connected to a terminal,
+the user is prompted to respond
+.IR yes ,
+.IR no ,
+or
+.I rename
+to whether the file should be overwritten. The responses
+can be abbreviated. If the user responds with
+.IR rename ,
+then
+.B mhstore
+prompts the user for the name of the new file to be created. If it is
+a relative path name (does not begin with '/'), then it is relative to
+the current directory. If it is an absolute or relative path to a
+directory that does not exist, the user will be prompted whether to
+create the directory. If standard input is not connected to a
+terminal,
+.I ask
+behaves the same as
+.IR always .
.SS "Reassembling Messages of Type message/partial"
.B mhstore
is also able to reassemble messages that have been
local-file
.IP \(bu 4
mail-server
+.IP \(bu 4
+url
.PP
For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
.B mhstore
The program should terminate with an exit status of zero if the
retrieval is successful, and a non-zero exit status otherwise.
.PP
-If this entry is not provided, then
+For the \*(lqurl\*(rq access types,
.B mhstore
-will use a simple
-built-in FTP client to perform the retrieval.
+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.
+.PP
.SS "The Content Cache"
When
.B mhstore
which is created automatically during
.B nmh
installation.
-
.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 %etcdir% \*(rq
+is checked.
+.PP
.fc ^ ~
.nf
.ta \w'%etcdir%/ExtraBigFileName 'u
^$MHSTORE~^Additional profile entries
^%etcdir%/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 mhlist (1),
+.IR mhshow (1),
+.IR sendfiles (1)
.SH DEFAULTS
.nf
.RB ` +folder "' defaults to the current folder"
.RB ` msgs "' defaults to cur"
.RB ` \-noauto '
+.RB ` \-clobber\ always '
.RB ` \-nocheck '
.RB ` \-rcache\ ask '
.RB ` \-wcache\ ask '
-
.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