X-Git-Url: http://git.marmaro.de/?p=mmh;a=blobdiff_plain;f=man%2Fmhstore.man1;h=4a821bf97432710bbe6cc4a960ebdbb57662b70d;hp=ec4c7a1e4c5ac8b6eacc67c8a8e92eeb715f6fa0;hb=18591f8e001ecedbee48a51c1d1f08ebaa1c15c8;hpb=5aa54cbb20ba640e73e6c9132f9b8c13bec07607 diff --git a/man/mhstore.man1 b/man/mhstore.man1 index ec4c7a1..4a821bf 100644 --- a/man/mhstore.man1 +++ b/man/mhstore.man1 @@ -19,12 +19,7 @@ mhstore \- store contents of MIME messages into files .IR content ] \&... .RB [ \-auto " | " \-noauto ] -.RB [ \-rcache -.IR policy ] -.RB [ \-wcache -.IR policy ] -.RB [ \-check " | " \-nocheck ] -.RB [ \-version ] +.RB [ \-Version ] .RB [ \-help ] .ad .SH DESCRIPTION @@ -58,18 +53,18 @@ 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 +If you specify this file as `-', 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 +.B mh message. It should .B NOT be in mail drop format (to convert a file in mail drop format to a folder of -.B nmh +.B mh messages, see .BR inc (1)). .PP @@ -88,7 +83,7 @@ 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 +The initial list of `standard' content types and subtypes can be found in RFC\-2046. .PP A list of commonly used contents is briefly reproduced here: @@ -111,71 +106,55 @@ video mpeg 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. +of the content, e.g., `audio'. To specify a specific +subtype, separate the two with a slash, e.g., `audio/basic'. 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. +upon. .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 +`native' (decoded) format. Two things must be determined: +the directory to store the content, and the filenames. +.PP +By default (or if the +.B \-auto +switch is given), +.B mhstore +uses filename information, contained in the message, if available. +(This information should be specified +as the attribute `name=filename' in the `Content-Type' header +for the content you are storing.) +Only the basename of this filename is considered. +If it begins with the character '.', '|', or '!', +or if it contains the character '%', automatic naming won't happen for +security reasons. (See below for the fall-back.) +.PP +Files are +written in the directory given by the `nmh-storage' profile entry, e.g., .PP .RS 5 nmh-storage: /tmp .RE .PP +(Note that `nmh-storage' is relative to the folder that contains +the message.) If this entry isn't present, the current working directory is used. +Attachments will get stored in either the `nmh-storage' or the current working +directory \(en in no case elsewhere. +Existing files get silently overwritten. .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 \-noauto +switch is given (or a filename 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 +`formatting string' to determine how the different contents should be stored. First, .B mhstore will look for an entry of @@ -195,12 +174,12 @@ mhstore-store- .PP to determine the formatting string. .PP -If the formatting string starts with a \*(lq+\*(rq character, then +If the formatting string starts with a `+' 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 +solely of a `+' character is interpreted to be the current folder. .PP -If the formatting string consists solely of a \*(lq-\*(rq character, +If the formatting string consists solely of a `\-' character, then the content is sent to the standard output. .PP If the formatting string starts with a '|', then the display string @@ -216,11 +195,9 @@ escapes (given below) in the display string will be expanded. 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. Note that if \*(lqnmh-storage\*(rq -is not an absolute path, it will be relative to the folder that -contains the message(s). +file name will be relative to either the value of `nmh-storage', +if set, or the current working directory. +Existing files get silently overwritten. .PP A command or pathname formatting string may contain the following escapes. If the content isn't part of a multipart (of any subtype @@ -241,19 +218,12 @@ listed above) content, the p-escapes are ignored. .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, +will use the value `+'. As a last resort, .B mhstore -will use the value \*(lq%m%P.%s\*(rq. +will use the value `%m%P.%s'. .PP Example profile entries might be: .PP @@ -262,7 +232,7 @@ Example profile entries might be: 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-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 @@ -271,7 +241,7 @@ mhstore-store-application/PostScript: %m%P.ps .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. +split into multiple messages of type `message/partial'. .PP When asked to store a content containing a partial message, .B mhstore @@ -313,141 +283,12 @@ are combined in the correct order. But if can not locate every partial necessary to reassemble the message, it will not store anything. -RE -.PP -By using the -.B \-auto -switch, -.B mhstore -will automatically do the extraction for you: -.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 9 - msg part type/subtype size description - 9 application/octet-stream 118K - (extract with uncompress | tar xvpf -) - type=tar - conversions=compress -% mhstore -auto 9 --- tar listing appears here as files are extracted -.fi .RE -.PP -As the second -.B tar -listing is generated, the files are extracted. -A prudent user will never put -.B \-auto -in the profile. -The correct procedure is to first use -.B mhlist -to find out what will be extracted. Then -.B mhstore -can be invoked with -.B \-auto -to perform the extraction. .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. -.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). +.B Mhstore +does not automatically retrieve message/external-body parts (anymore), +but prints the relevant information to enable the user to retrieve +the files manually. .SS "User Environment" Because the display environment in which .B mhstore @@ -470,7 +311,7 @@ user profile, e.g., .RE .PP which is created automatically during -.B nmh +.B mmh installation. .SH FILES @@ -489,24 +330,18 @@ installation. .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) +mhbuild(1), mhlist(1), show(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 ` msgs "' defaults to the current message" +.RB ` \-auto ' .SH CONTEXT If a folder is given, it will become the current folder. The last @@ -514,3 +349,5 @@ message selected will become the current message. .SH BUGS Partial messages contained within a multipart content are not reassembled. +.PP +Existing files get silently overwritten.