X-Git-Url: https://diplodocus.org/git/nmh/blobdiff_plain/207d657cf4495be3eb44ccde94e807692665f5e2..ec173fd2c:/man/mhstore.man?ds=sidebyside diff --git a/man/mhstore.man b/man/mhstore.man index be99f0de..cb10d62c 100644 --- a/man/mhstore.man +++ b/man/mhstore.man @@ -1,23 +1,31 @@ -.\" +.TH MHSTORE %manext1% 2015-02-06 "%nmhversion%" +. .\" %nmhwarning% -.\" -.TH MHSTORE %manext1% "%nmhdate%" MH.6.8 [%nmhversion%] +. .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 ] @@ -26,72 +34,84 @@ mhstore \- store contents of MIME messages into files .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 @@ -117,71 +137,96 @@ 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 +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-/ @@ -205,17 +250,19 @@ folder. 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 @@ -231,7 +278,7 @@ listed above) content, the p-escapes are ignored. .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 @@ -243,15 +290,13 @@ 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 +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 @@ -270,6 +315,14 @@ mhstore-store-application/PostScript: %m%P.ps .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 @@ -316,12 +369,12 @@ 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 +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 , @@ -343,26 +396,26 @@ 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 +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 -% mhlist 5-8 +$ 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 +$ mhstore 5-8 reassembling partials 5,6,7,8 to folder inbox as message 9 -% mhlist -verbose 9 +$ mhlist -verbose 9 msg part type/subtype size description 9 application/octet-stream 118K (extract with uncompress | tar xvpf -) @@ -375,16 +428,14 @@ 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 +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 @@ -395,6 +446,8 @@ ftp local-file .IP \(bu 4 mail-server +.IP \(bu 4 +url .PP For the \*(lqanon-ftp\*(rq and \*(lqftp\*(rq access types, .B mhstore @@ -422,6 +475,19 @@ local filename .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 @@ -437,19 +503,17 @@ 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 +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 @@ -475,39 +539,63 @@ nmh-private-cache: .cache .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 @@ -516,15 +604,18 @@ installation. ^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-*~^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" @@ -534,10 +625,9 @@ mhbuild(1), mhlist(1), mhshow(1), sendfiles(1) .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.