.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MIME-CONSTRUCT 1p" .TH MIME-CONSTRUCT 1p "2010-06-23" "perl v5.10.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" mime\-construct \- construct and optionally mail MIME messages .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBmime-construct\fR \fIswitch\fR... .PP Sorry, it's hard to provide a meaningful synopsis. See the examples. .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBmime-construct\fR constructs and (by default) mails \s-1MIME\s0 messages. It is entirely driven from the command line, it is designed to be used by other programs, or people who act like programs. .SH "OPTIONS" .IX Header "OPTIONS" .SS "Global Settings" .IX Subsection "Global Settings" .IP "\fB\-\-debug\fR" 4 .IX Item "--debug" Turn debugging on. .IP "\fB\-\-help\fR" 4 .IX Item "--help" Show the usage message and die. .IP "\fB\-\-output\fR" 4 .IX Item "--output" Don't mail the generated message, print it to stdout instead. This loses \fB\-\-bcc\fR info. .IP "\fB\-\-subpart\fR" 4 .IX Item "--subpart" Generate a subpart which can be used in another \s-1MIME\s0 message, rather than a top-level \s-1MIME\s0 message itself. This turns on \fB\-\-output\fR and changes some internal semantics a bit. See the examples. .IP "\fB\-\-version\fR" 4 .IX Item "--version" Print the version and exit successfully, if this is the only arg. Otherwise, print the version and die. .SS "Main Header" .IX Subsection "Main Header" These arguments add text to the top-level header of the message, or control who it gets sent to. .IP "\fB\-\-bcc\fR \fIaddress\fR" 4 .IX Item "--bcc address" Add \fIaddress\fR to the recipient list. This doesn't actually add anything to the header, of course. If you're not actually mailing the message (if you use \fB\-\-output\fR or \fB\-\-subpart\fR) \fB\-\-bcc\fR will have no effect. .IP "\fB\-\-cc\fR \fIaddress\fR" 4 .IX Item "--cc address" Add an address to the \fBCc:\fR list. .IP "\fB\-\-embedded\-to\fR" 4 .IX Item "--embedded-to" Send the message to the recipients already listed in the header, in addition to those given with \fB\-\-to\fR, \fB\-\-cc\fR, and \fB\-\-bcc\fR. This makes sense if you use the \fB\-\-header\fR switch to add your own \fBTo:\fR or \&\fBCc:\fR. In this case you probably don't want to use \fB\-\-to\fR or \fB\-\-cc\fR because they would create new headers rather than adding to the ones already in the message. .Sp This switch passes the \fB\-t\fR switch to sendmail (\fBmime-construct\fR doesn't try to parse the headers you provide), so it doesn't really do anything if you're not mailing the message. .IP "\fB\-\-header\fR \fIstr\fR" 4 .IX Item "--header str" Add arbitrary text to the header. The \fIstr\fR can be anything you like, including multiple lines. You can create invalid messages this way. If you include a blank line in the \fIstr\fR you'll really screw up the message. .IP "\fB\-\-multipart\fR \fIstr\fR" 4 .IX Item "--multipart str" This specifies the multipart content type and options. The default is \&\f(CW\*(C`multipart/mixed\*(C'\fR. Don't include a \f(CW\*(C`boundary\*(C'\fR setting, that's supplied by \fBmime-construct\fR. .Sp It's okay if you specify the \fB\-\-multipart\fR type but the message turns out to be a single part, the type you supply will just be ignored. .IP "\fB\-\-prelude\fR \fIstr\fR" 4 .IX Item "--prelude str" This adds \fIstr\fR to the multipart prelude text. If you specify \&\fB\-\-prelude\fR multiple times the \fIstr\fRs will all be concatenated. .Sp There isn't any default for this text. It seems to me that nowadays adding an explanation of \s-1MIME\s0 to the beginning of a message is like explaining how to use a seat buckle to people who are riding in an airplane. .Sp It's okay if you specify the \fB\-\-prelude\fR but the message turns out to be a single part, the prelude you supply will just be ignored. .IP "\fB\-\-subject\fR \fIstr\fR" 4 .IX Item "--subject str" Specify the subject for the message. .IP "\fB\-\-to\fR \fIaddress\fR" 4 .IX Item "--to address" Add an address to the \fBTo:\fR list. .SS "Per-part Header" .IX Subsection "Per-part Header" These switches control the per-part headers. If the message turns out not to be multipart they actually add data to the top level header. .PP Each of these applies only to the next part output. After each part is output they are reset to their default values. It doesn't make sense to use them without a following part, so \fBmime-construct\fR will sputter and die if you try to do that. .IP "\fB\-\-attachment\fR \fIname\fR" 4 .IX Item "--attachment name" This adds a \f(CW\*(C`Content\-Disposition: attachment\*(C'\fR header with the given \&\fIname\fR as the value of the \f(CW\*(C`filename\*(C'\fR attribute. It's just a convenience, since \fBmime-construct\fR is often used to send files as attachments. .Sp Using \fB\-\-attachment\fR \fIname\fR does not cause \fBmime-construct\fR to read any data from the file called \fIname\fR! It just uses that name in the header. The actual data which will go into this part of the message comes from one of the regular part output switches (given below). .Sp You might prefer to use the \fB\-\-file\-attach\fR switch, which does read from the \fIname\fRd file. .IP "\fB\-\-encoding\fR \fItype\fR" 4 .IX Item "--encoding type" This specifies the type of encoding you want this part to use. You normally shouldn't use this switch, though. If this switch isn't used \&\fBmime-construct\fR will choose an appropriate encoding. .Sp The data you supply mustn't be encoded already, \fBmime-construct\fR will encode it according to the \fItype\fR you specify here. Valid encodings are \fB7bit\fR, \fB8bit\fR, \fBbinary\fR, \fBquoted-printable\fR, and \fBbase64\fR. It's easy to generate an illegal \s-1MIME\s0 message by specifying the encoding yourself. .IP "\fB\-\-part\-header\fR \fIstr\fR" 4 .IX Item "--part-header str" Add arbitrary text to the per-part header. The \fIstr\fR can be anything you like, including multiple lines. You can create invalid messages this way. If you include a blank line in the \fIstr\fR you'll really screw up the message. .IP "\fB\-\-type\fR \fItype\fR" 4 .IX Item "--type type" Specify the content type for this part. If you don't specify a \fB\-\-type\fR it defaults to \f(CW\*(C`text/plain\*(C'\fR. The \fItype\fR you supply can contain not only the type proper but also options. The whole thing will just be plopped onto the end of \f(CW\*(C`Content\-Type:\*(C'\fR and stuck into the header. .Sp You might prefer to use the \fB\-\-file\-auto\fR or \fB\-\-file\-attach\fR switches, which set the \fB\-\-type\fR automatically based on a file's name. .SS "Part Output" .IX Subsection "Part Output" These switches add data to the body of the message. You use one of these for each for each part of a multipart message (or just one of them if the message isn't to be multipart). .IP "\fB\-\-file\fR \fIpath\fR" 4 .IX Item "--file path" .PD 0 .IP "\fB\-\-file\-auto\fR \fIpath\fR" 4 .IX Item "--file-auto path" .IP "\fB\-\-file\-attach\fR \fIpath\fR" 4 .IX Item "--file-attach path" .IP "\fB\-\-attach\fR \fIpath\fR" 4 .IX Item "--attach path" .IP "\fB\-\-string\fR \fIstr\fR" 4 .IX Item "--string str" .IP "\fB\-\-body\fR \fIstr\fR" 4 .IX Item "--body str" .PD Use the contents of the file \fIpath\fR or the literal string \fIstr\fR as the body of this part. .Sp \&\fB\-\-file\-auto\fR causes the Content-Type to be set based on the file's name, if possible. .Sp \&\fB\-\-file\-attach\fR does that and sets the \fB\-\-attachment\fR name as well. .Sp Be sure to include the trailing newline on \fIstr\fR unless there really isn't supposed to be one. If you leave the trailing newline off the part will have to be encoded in \f(CW\*(C`base64\*(C'\fR (because \f(CW\*(C`quoted\-printable\*(C'\fR has an artificial limitation which prevents it from being able to encode such a data stream). .Sp \&\fB\-\-attach\fR is an alias for \fB\-\-file\-attach\fR, and \fB\-\-body\fR is an alias for \fB\-\-string\fR. .IP "\fB\-\-subpart\-file\fR \fIpath\fR" 4 .IX Item "--subpart-file path" .PD 0 .IP "\fB\-\-subpart\-string\fR \fIstr\fR" 4 .IX Item "--subpart-string str" .PD Use either the contents of \fIpath\fR or \fIstr\fR itself as the body of this part, but treat it as a subpart. This means that the data contains both some headers and some text. It also means that you can't use \fB\-\-type\fR or \fB\-\-encoding\fR for this part. .Sp Normally the \fIpath\fR or \fIstr\fR will have been generated by a different invocation of \fBmime-construct\fR which was given the \fB\-\-subpart\fR switch. .PP Arguments to switches which take a file name (such as \fB\-\-file\fR and \&\fB\-\-subpart\-file\fR) can have some magic. If there is no file with the \fIpath\fR supplied a regular Perl \fIopen()\fR is done on it. See \&\*(L"\s-1EXAMPLES\s0\*(R". .SH "EXAMPLES" .IX Header "EXAMPLES" The examples assume that \f(CW$nl\fR contains a newline. The other variables used are I hope self-explanatory. .PP Send a simple message. .PP .Vb 1 \& mime\-construct \-\-to "$recip" \-\-subject \*(Aqhi there\*(Aq \-\-string "$body" .Ve .PP Send a message which is read from stdin. .PP .Vb 1 \& fortune | mime\-construct \-\-to "$recip" \-\-subject fortune \-\-file \- .Ve .PP Send a plain text part and attach a file, setting the file's content type and \fB\-\-attachment\fR name automatically. .PP .Vb 3 \& mime\-construct \-\-to "$recip" \-\-subject "$file" \e \& \-\-string "Here\*(Aqs the file I told you about.$nl" \e \& \-\-file\-attach "$file" .Ve .PP Most people think of attachments as multipart messages, but they don't have to be. This generates a zip of all the files in the current directory and sends them as an attachment but as a single part message. .PP .Vb 3 \& zip \-q \- * | \& mime\-construct \-\-to "$recip" \-\-subject \*(Aqzipped directory\*(Aq \e \& \-\-attachment dir.zip \-\-type application/zip \-\-file \- .Ve .PP You can use the full expressiveness of Perl's \fIopen()\fR when constructing file names. Eg, you can run processes \&\s-1XXX\s0 bad examples, there's no file names .PP .Vb 4 \& mime\-construct \-\-to "$recip" \-\-subject "$subject" \e \& \-\-string "Here are those two files you wanted.$nl" \e \& \-\-type application/x\-gzip \-\-attachment file1.gz \-\-file \*(Aqgzip \-c file1 |\*(Aq \e \& \-\-type application/x\-gzip \-\-attachment file1.gz \-\-file \*(Aqgzip \-c file2 |\*(Aq .Ve .PP or read from alternate file descriptors (\f(CW\*(C`<&=4\*(C'\fR to read from file descriptor 4) or whatever. See perlopentut for a tutorial. .PP Here's an example of using a separate invocation of \fBmime-construct\fR to create a subpart. This creates a message which has two parts at the top level. The first part is some text, the second part is a digest. The digest itself is a multipart message which contains a number of message/rfc822 parts. .PP .Vb 5 \& msg_args= \& for msg in $msg_list \& do \& msg_args="$msg_args \-\-type message/rfc822 \-\-file $msg" \& done \& \& set fnord \& for recip in $recip_list \& do \& set "$@" \-\-bcc $recip \& done \& shift \& \& mime\-construct \-\-subpart \-\-multipart multipart/digest $msg_args | \& mime\-construct \e \& \-\-header "To: Digest recipients:;$nl" \e \& \-\-subject \*(AqFoo digest\*(Aq \e \& "$@" \e \& \-\-file "$introduction" \e \& \-\-subpart\-file \- .Ve .PP Here is how to send an encrypted messages (multipart/encrypted, as defined in \s-1RFC\s0 1847). You use \fBmime-construct\fR \f(CW\*(C`\-\-subpart\*(C'\fR to generate the real message you want to send (which can be kind of \&\s-1MIME\s0 message \*(-- non-text, multi-part, what have you), then encrypt that and use another \fBmime-construct\fR to contruct and send the multipart/encrypted message which contains it. .PP .Vb 2 \& enc_type=application/pgp\-encrypted \& enc_params="Version: 1$nl" \& \& mime\-construct \-\-subpart \-\-file body \-\-file\-auto image.jpg | \& gpg \-\-encrypt \-\-armor \-r "$recip" | \& mime\-construct \-\-output \e \& \-\-to "$recip" \e \& \-\-subject "$subject" \e \& \-\-multipart "multipart/encrypted; protocol=\e"$enc_type\e"" \e \& \-\-type "$enc_type" \e \& \-\-string "$enc_params" \e \& \-\-type application/octet\-stream \e \& \-\-file \- .Ve .SH "BUGS" .IX Header "BUGS" The body of the message is always held in memory, so you can expect problems if you work with bodies which are large compared to the amount of memory you've got. .SH "AVAILABILITY" .IX Header "AVAILABILITY" The code is licensed under the \s-1GNU\s0 \s-1GPL\s0. Check http://www.argon.org/~roderick/ for updated versions. .SH "AUTHOR" .IX Header "AUTHOR" Roderick Schertler