--- /dev/null
+.\"
+.\" %nmhwarning%
+.\"
+.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%]
+.SH NAME
+mhstore \- store contents of MIME messages into files
+.SH SYNOPSIS
+.HP 5
+.na
+.B mhstore
+.RI [ +folder ]
+.RI [ msgs ]
+.RB [ \-file
+.IR file ]
+.RB [ \-part
+.IR number ]
+\&...
+.RB [ \-type
+.IR content ]
+\&...
+.RB [ \-auto " | " \-noauto ]
+.RB [ \-verbose " | " \-noverbose ]
+.RB [ \-rcache
+.IR policy ]
+.RB [ \-wcache
+.IR policy ]
+.RB [ \-check " | " \-nocheck ]
+.RB [ \-version ]
+.RB [ \-help ]
+.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.
+.PP
+.B mhstore
+manipulates multi-media messages as specified in
+RFC\-2045 thru 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
+the message are not stored. By using the
+.B \-part
+and
+.B \-type
+switches, you may limit the scope of
+.B mhstore
+to particular
+subparts (of a multipart content) and/or particular content types.
+.PP
+The option
+.B \-file
+.I file
+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
+.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
+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
+.B nmh
+messages, see
+.BR 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
+.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
+another multipart content, the
+.B \-part
+switch will not prevent
+the content from being acted upon.
+.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.
+.PP
+A list of commonly used contents is briefly reproduced here:
+.PP
+.RS 5
+.nf
+.ta \w'application 'u
+Type Subtypes
+---- --------
+text plain, enriched
+multipart mixed, alternative, digest, parallel
+message rfc822, partial, external-body
+application octet-stream, postscript
+image jpeg, gif, png
+audio basic
+video mpeg
+.fi
+.RE
+.PP
+A legal MIME message must contain a subtype specification.
+.PP
+To specify a content, regardless of its subtype, just use the name
+of the content, e.g., \*(lqaudio\*(rq. To specify a specific
+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
+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
+.B \-type
+switch must be used twice: once for message/external-body
+and once for the content externally referenced.
+.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
+.B mhstore
+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.,
+.PP
+.RS 5
+nmh-storage: /tmp
+.RE
+.PP
+If this entry isn't present,
+the current working directory is used.
+.PP
+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 \&.mmh/profile
+file.
+.PP
+If the
+.B \-auto
+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,
+.B mhstore
+will look for an entry of
+the form:
+.PP
+.RS 5
+mhstore-store-<type>/<subtype>
+.RE
+.PP
+to determine the formatting string. If this isn't found,
+.B mhstore
+will look for an entry of the form:
+.PP
+.RS 5
+mhstore-store-<type>
+.RE
+.PP
+to determine the formatting string.
+.PP
+If the formatting string starts with a \*(lq+\*(rq character, then
+content is stored in the named folder. A formatting string consisting
+solely of a \*(lq+\*(rq character is interpreted to be the current
+folder.
+.PP
+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
+.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,
+.B mhstore
+will change to the appropriate directory, and any
+escapes (given below) in the display string will be expanded.
+.PP
+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
+the current working directory. Any escapes (given below) will be
+expanded, except for the a-escape.
+.PP
+A command or pathname formatting string may contain the following
+escapes. If the content isn't part of a multipart (of any subtype
+listed above) content, the p-escapes are ignored.
+.PP
+.RS 5
+.nf
+.ta \w'%P 'u
+%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
+%t Insert content type
+%s Insert content subtype
+%% Insert character %
+.fi
+.RE
+.PP
+If no formatting string is found,
+.B mhstore
+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
+.B mhstore
+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
+will use the value \*(lq%m%P.%s\*(rq.
+.PP
+Example profile entries might be:
+.PP
+.RS 5
+.nf
+mhstore-store-text: %m%P.txt
+mhstore-store-text: +inbox
+mhstore-store-message/partial: +
+mhstore-store-audio/basic: | raw2audio -e ulaw -s 8000 -c 1 > %m%P.au
+mhstore-store-image/jpeg: %m%P.jpg
+mhstore-store-application/PostScript: %m%P.ps
+.fi
+.RE
+.PP
+.SS "Reassembling Messages of Type message/partial"
+.B mhstore
+is also able to reassemble messages that have been
+split into multiple messages of type \*(lqmessage/partial\*(rq.
+.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
+.BR sendfiles ),
+you can easily reassemble them all into a single
+message in the following fashion:
+.PP
+.RS 5
+.nf
+% mhlist 5-8
+ msg part type/subtype size description
+ 5 message/partial 47K part 1 of 4
+ 6 message/partial 47K part 2 of 4
+ 7 message/partial 47K part 3 of 4
+ 8 message/partial 18K part 4 of 4
+% mhstore 5-8
+reassembling partials 5,6,7,8 to folder inbox as message 9
+% mhlist -verbose 9
+ msg part type/subtype size description
+ 9 application/octet-stream 118K
+ (extract with uncompress | tar xvpf -)
+ type=tar
+ conversions=compress
+.fi
+.RE
+.PP
+This will store exactly one message, containing the sum of the
+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
+.B mhstore
+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
+anon-ftp
+.IP \(bu 4
+ftp
+.IP \(bu 4
+local-file
+.IP \(bu 4
+mail-server
+.PP
+For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types,
+.B mhstore
+will look for the \*(lqnmh-access-ftp\*(rq
+profile entry, e.g.,
+.PP
+.RS 5
+nmh-access-ftp: myftp.sh
+.RE
+.PP
+to determine the pathname of a program to perform the FTP retrieval.
+This program is invoked with these arguments:
+.PP
+.RS 5
+.nf
+domain name of FTP-site
+username
+password
+remote directory
+remote filename
+local filename
+\*(lqascii\*(rq or \*(lqbinary\*(rq
+.fi
+.RE
+.PP
+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
+.B mhstore
+will use a simple
+built-in FTP client to perform the retrieval.
+.SS "The Content Cache"
+When
+.B mhstore
+encounters an external content containing a
+\*(lqContent-ID:\*(rq field, and if the content allows caching, then
+depending on the caching behavior of
+.BR mhstore ,
+the content might be read from or written to a cache.
+.PP
+The caching behavior of
+.B mhstore
+is controlled with the
+.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
+specified: \*(lqpublic\*(rq, indicating that
+.B mhstore
+should make use
+of a publically-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
+.B mhstore
+should ask the user.
+.PP
+There are two directories where contents may be cached: the profile entry
+\*(lqnmh-cache\*(rq names a directory containing world-readable contents, and,
+the profile entry \*(lqnmh-private-cache\*(rq names a directory containing
+private contents. The former should be an absolute (rooted) directory
+name.
+.PP
+For example,
+.PP
+.RS 5
+nmh-cache: /tmp
+.RE
+.PP
+might be used if you didn't care that the cache got wiped after each
+reboot of the system. The private chace is interpreted relative to the user's
+mail storage, if not rooted, e.g.,
+.PP
+.RS 5
+nmh-private-cache: .cache
+.RE
+.PP
+(which is the default value).
+.SS "User Environment"
+Because the display environment in which
+.B mhstore
+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,
+.B mhstore
+will attempt to consult one other additional
+user profile, e.g.,
+.PP
+.RS 5
+%etcdir%/mhn.defaults
+.RE
+.PP
+which is created automatically during
+.B nmh
+installation.
+
+.SH FILES
+.fc ^ ~
+.nf
+.ta \w'%etcdir%/ExtraBigFileName 'u
+^$HOME/.mmh/profile~^The user profile
+^$MHSTORE~^Additional profile entries
+^%etcdir%/mhn.defaults~^System default MIME profile entries
+.fi
+
+.SH "PROFILE COMPONENTS"
+.fc ^ ~
+.nf
+.ta 2.4i
+.ta \w'ExtraBigProfileName 'u
+^Path:~^To determine the user's mail storage
+^Current\-Folder:~^To find the default current folder
+^nmh-access-ftp:~^Program to retrieve contents via FTP
+^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)
+
+.SH DEFAULTS
+.nf
+.RB ` +folder "' defaults to the current folder"
+.RB ` msgs "' defaults to cur"
+.RB ` \-noauto '
+.RB ` \-nocheck '
+.RB ` \-rcache ask '
+.RB ` \-wcache ask '
+.RB ` \-noverbose '
+
+.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 / mmh / blobdiff