X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fmhstore.man1;fp=man%2Fmhstore.man1;h=acf36947a27471aa1db821b9f25f6fae4a3fc6de;hp=0000000000000000000000000000000000000000;hb=5aaedc4256d58afe2481d667afdcb5162a914ba9;hpb=2676fdf95667cfa0fec45372dbb956c8645c1119 diff --git a/man/mhstore.man1 b/man/mhstore.man1 new file mode 100644 index 0000000..acf3694 --- /dev/null +++ b/man/mhstore.man1 @@ -0,0 +1,479 @@ +.\" +.\" %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-/ +.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- +.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-*~^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.