Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / devtools / v8plus / man / man3 / Net::SMTP.3

.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.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.  | will give a
.\" real vertical bar.  \*(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-|\(bv\*(Tr
.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\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" 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 "Net::SMTP 3"
.TH Net::SMTP 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide"
.SH "NAME"
Net::SMTP \- Simple Mail Transfer Protocol Client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Net::SMTP;
.Ve
.PP
.Vb 3
\&    # Constructors
\&    $smtp = Net::SMTP->new('mailhost');
\&    $smtp = Net::SMTP->new('mailhost', Timeout => 60);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module implements a client interface to the \s-1SMTP\s0 and \s-1ESMTP\s0
protocol, enabling a perl5 application to talk to \s-1SMTP\s0 servers. This
documentation assumes that you are familiar with the concepts of the
\&\s-1SMTP\s0 protocol described in \s-1RFC821\s0.
.PP
A new Net::SMTP object must be created with the \fInew\fR method. Once
this has been done, all \s-1SMTP\s0 commands are accessed through this object.
.PP
The Net::SMTP class is a subclass of Net::Cmd and IO::Socket::INET.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This example prints the mail domain name of the \s-1SMTP\s0 server known as mailhost:
.PP
.Vb 1
\&    #!/usr/local/bin/perl -w
.Ve
.PP
.Vb 1
\&    use Net::SMTP;
.Ve
.PP
.Vb 3
\&    $smtp = Net::SMTP->new('mailhost');
\&    print $smtp->domain,"\en";
\&    $smtp->quit;
.Ve
.PP
This example sends a small message to the postmaster at the \s-1SMTP\s0 server
known as mailhost:
.PP
.Vb 1
\&    #!/usr/local/bin/perl -w
.Ve
.PP
.Vb 1
\&    use Net::SMTP;
.Ve
.PP
.Vb 1
\&    $smtp = Net::SMTP->new('mailhost');
.Ve
.PP
.Vb 2
\&    $smtp->mail($ENV{USER});
\&    $smtp->to('postmaster');
.Ve
.PP
.Vb 5
\&    $smtp->data();
\&    $smtp->datasend("To: postmaster\en");
\&    $smtp->datasend("\en");
\&    $smtp->datasend("A simple test message\en");
\&    $smtp->dataend();
.Ve
.PP
.Vb 1
\&    $smtp->quit;
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.IP "new ( [ \s-1HOST\s0 ] [, \s-1OPTIONS\s0 ] )" 4
.IX Item "new ( [ HOST ] [, OPTIONS ] )"
This is the constructor for a new Net::SMTP object. \f(CW\*(C`HOST\*(C'\fR is the
name of the remote host to which an \s-1SMTP\s0 connection is required.
.Sp
\&\f(CW\*(C`HOST\*(C'\fR is optional. If \f(CW\*(C`HOST\*(C'\fR is not given then it may instead be
passed as the \f(CW\*(C`Host\*(C'\fR option described below. If neither is given then
the \f(CW\*(C`SMTP_Hosts\*(C'\fR specified in \f(CW\*(C`Net::Config\*(C'\fR will be used.
.Sp
\&\f(CW\*(C`OPTIONS\*(C'\fR are passed in a hash like fashion, using key and value pairs.
Possible options are:
.Sp
\&\fBHello\fR \- \s-1SMTP\s0 requires that you identify yourself. This option
specifies a string to pass as your mail domain. If not given localhost.localdomain
will be used.
.Sp
\&\fBHost\fR \- \s-1SMTP\s0 host to connect to. It may be a single scalar, as defined for
the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
an array with hosts to try in turn. The \*(L"host\*(R" method will return the value
which was used to connect to the host.
.Sp
\&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
to IO::Socket to allow binding the socket to a local port.
.Sp
\&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
\&\s-1SMTP\s0 server (default: 120)
.Sp
\&\fBExactAddresses\fR \- If true the all \s-1ADDRESS\s0 arguments must be as
defined by \f(CW\*(C`addr\-spec\*(C'\fR in \s-1RFC2822\s0. If not given, or false, then
Net::SMTP will attempt to extract the address from the value passed.
.Sp
\&\fBDebug\fR \- Enable debugging information
.Sp
Example:
.Sp
.Vb 5
\&    $smtp = Net::SMTP->new('mailhost',
\&                           Hello => 'my.mail.domain'
\&                           Timeout => 30,
\&                           Debug   => 1,
\&                          );
.Ve
.Sp
.Vb 7
\&    # the same
\&    $smtp = Net::SMTP->new(
\&                           Host => 'mailhost',
\&                           Hello => 'my.mail.domain'
\&                           Timeout => 30,
\&                           Debug   => 1,
\&                          );
.Ve
.Sp
.Vb 5
\&    # Connect to the default server from Net::config
\&    $smtp = Net::SMTP->new(
\&                           Hello => 'my.mail.domain'
\&                           Timeout => 30,
\&                          );
.Ve
.SH "METHODS"
.IX Header "METHODS"
Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
value, with \fItrue\fR meaning that the operation was a success. When a method
states that it returns a value, failure will be returned as \fIundef\fR or an
empty list.
.IP "banner ()" 4
.IX Item "banner ()"
Returns the banner message which the server replied with when the
initial connection was made.
.IP "domain ()" 4
.IX Item "domain ()"
Returns the domain that the remote \s-1SMTP\s0 server identified itself as during
connection.
.IP "hello ( \s-1DOMAIN\s0 )" 4
.IX Item "hello ( DOMAIN )"
Tell the remote server the mail domain which you are in using the \s-1EHLO\s0
command (or \s-1HELO\s0 if \s-1EHLO\s0 fails).  Since this method is invoked
automatically when the Net::SMTP object is constructed the user should
normally not have to call it manually.
.IP "host ()" 4
.IX Item "host ()"
Returns the value used by the constructor, and passed to IO::Socket::INET,
to connect to the host.
.IP "etrn ( \s-1DOMAIN\s0 )" 4
.IX Item "etrn ( DOMAIN )"
Request a queue run for the \s-1DOMAIN\s0 given.
.IP "auth ( \s-1USERNAME\s0, \s-1PASSWORD\s0 )" 4
.IX Item "auth ( USERNAME, PASSWORD )"
Attempt \s-1SASL\s0 authentication.
.IP "mail ( \s-1ADDRESS\s0 [, \s-1OPTIONS\s0] )" 4
.IX Item "mail ( ADDRESS [, OPTIONS] )"
.PD 0
.IP "send ( \s-1ADDRESS\s0 )" 4
.IX Item "send ( ADDRESS )"
.IP "send_or_mail ( \s-1ADDRESS\s0 )" 4
.IX Item "send_or_mail ( ADDRESS )"
.IP "send_and_mail ( \s-1ADDRESS\s0 )" 4
.IX Item "send_and_mail ( ADDRESS )"
.PD
Send the appropriate command to the server \s-1MAIL\s0, \s-1SEND\s0, \s-1SOML\s0 or \s-1SAML\s0. \f(CW\*(C`ADDRESS\*(C'\fR
is the address of the sender. This initiates the sending of a message. The
method \f(CW\*(C`recipient\*(C'\fR should be called for each address that the message is to
be sent to.
.Sp
The \f(CW\*(C`mail\*(C'\fR method can some additional \s-1ESMTP\s0 \s-1OPTIONS\s0 which is passed
in hash like fashion, using key and value pairs.  Possible options are:
.Sp
.Vb 6
\& Size        => <bytes>
\& Return      => "FULL" | "HDRS"
\& Bits        => "7" | "8" | "binary"
\& Transaction => <ADDRESS>
\& Envelope    => <ENVID>
\& XVERP       => 1
.Ve
.Sp
The \f(CW\*(C`Return\*(C'\fR and \f(CW\*(C`Envelope\*(C'\fR parameters are used for \s-1DSN\s0 (Delivery
Status Notification).
.IP "reset ()" 4
.IX Item "reset ()"
Reset the status of the server. This may be called after a message has been 
initiated, but before any data has been sent, to cancel the sending of the
message.
.IP "recipient ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0, [...]] [, \s-1OPTIONS\s0 ] )" 4
.IX Item "recipient ( ADDRESS [, ADDRESS, [...]] [, OPTIONS ] )"
Notify the server that the current message should be sent to all of the
addresses given. Each address is sent as a separate command to the server.
Should the sending of any address result in a failure then the process is
aborted and a \fIfalse\fR value is returned. It is up to the user to call
\&\f(CW\*(C`reset\*(C'\fR if they so desire.
.Sp
The \f(CW\*(C`recipient\*(C'\fR method can also pass additional case-sensitive \s-1OPTIONS\s0 as an
anonymous hash using key and value pairs.  Possible options are:
.Sp
.Vb 2
\&  Notify  => ['NEVER'] or ['SUCCESS','FAILURE','DELAY']  (see below)
\&  SkipBad => 1        (to ignore bad addresses)
.Ve
.Sp
If \f(CW\*(C`SkipBad\*(C'\fR is true the \f(CW\*(C`recipient\*(C'\fR will not return an error when a bad
address is encountered and it will return an array of addresses that did
succeed.
.Sp
.Vb 5
\&  $smtp->recipient($recipient1,$recipient2);  # Good
\&  $smtp->recipient($recipient1,$recipient2, { SkipBad => 1 });  # Good
\&  $smtp->recipient($recipient1,$recipient2, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
\&  @goodrecips=$smtp->recipient(@recipients, { Notify => ['FAILURE'], SkipBad => 1 });  # Good
\&  $smtp->recipient("$recipient,$recipient2"); # BAD
.Ve
.Sp
Notify is used to request Delivery Status Notifications (DSNs), but your
\&\s-1SMTP/ESMTP\s0 service may not respect this request depending upon its version and
your site's \s-1SMTP\s0 configuration.
.Sp
Leaving out the Notify option usually defaults an \s-1SMTP\s0 service to its default
behavior equivalent to ['\s-1FAILURE\s0'] notifications only, but again this may be
dependent upon your site's \s-1SMTP\s0 configuration.
.Sp
The \s-1NEVER\s0 keyword must appear by itself if used within the Notify option and \*(L"requests
that a \s-1DSN\s0 not be returned to the sender under any conditions.\*(R"
.Sp
.Vb 1
\&  {Notify => ['NEVER']}
.Ve
.Sp
.Vb 1
\&  $smtp->recipient(@recipients, { Notify => ['NEVER'], SkipBad => 1 });  # Good
.Ve
.Sp
You may use any combination of these three values '\s-1SUCCESS\s0','\s-1FAILURE\s0','\s-1DELAY\s0' in
the anonymous array reference as defined by \s-1RFC3461\s0 (see http://rfc.net/rfc3461.html
for more information.  Note: quotations in this topic from same.).
.Sp
A Notify parameter of '\s-1SUCCESS\s0' or '\s-1FAILURE\s0' \*(L"requests that a \s-1DSN\s0 be issued on
successful delivery or delivery failure, respectively.\*(R"
.Sp
A Notify parameter of '\s-1DELAY\s0' \*(L"indicates the sender's willingness to receive
delayed DSNs.  Delayed DSNs may be issued if delivery of a message has been
delayed for an unusual amount of time (as determined by the Message Transfer
Agent (\s-1MTA\s0) at which the message is delayed), but the final delivery status
(whether successful or failure) cannot be determined.  The absence of the \s-1DELAY\s0
keyword in a \s-1NOTIFY\s0 parameter requests that a \*(R"delayed\*(L" \s-1DSN\s0 \s-1NOT\s0 be issued under
any conditions.\*(R"
.Sp
.Vb 1
\&  {Notify => ['SUCCESS','FAILURE','DELAY']}
.Ve
.Sp
.Vb 1
\&  $smtp->recipient(@recipients, { Notify => ['FAILURE','DELAY'], SkipBad => 1 });  # Good
.Ve
.IP "to ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "to ( ADDRESS [, ADDRESS [...]] )"
.PD 0
.IP "cc ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "cc ( ADDRESS [, ADDRESS [...]] )"
.IP "bcc ( \s-1ADDRESS\s0 [, \s-1ADDRESS\s0 [...]] )" 4
.IX Item "bcc ( ADDRESS [, ADDRESS [...]] )"
.PD
Synonyms for \f(CW\*(C`recipient\*(C'\fR.
.IP "data ( [ \s-1DATA\s0 ] )" 4
.IX Item "data ( [ DATA ] )"
Initiate the sending of the data from the current message. 
.Sp
\&\f(CW\*(C`DATA\*(C'\fR may be a reference to a list or a list. If specified the contents
of \f(CW\*(C`DATA\*(C'\fR and a termination string \f(CW".\er\en"\fR is sent to the server. And the
result will be true if the data was accepted.
.Sp
If \f(CW\*(C`DATA\*(C'\fR is not specified then the result will indicate that the server
wishes the data to be sent. The data must then be sent using the \f(CW\*(C`datasend\*(C'\fR
and \f(CW\*(C`dataend\*(C'\fR methods described in Net::Cmd.
.IP "expand ( \s-1ADDRESS\s0 )" 4
.IX Item "expand ( ADDRESS )"
Request the server to expand the given address Returns an array
which contains the text read from the server.
.IP "verify ( \s-1ADDRESS\s0 )" 4
.IX Item "verify ( ADDRESS )"
Verify that \f(CW\*(C`ADDRESS\*(C'\fR is a legitimate mailing address.
.Sp
Most sites usually disable this feature in their \s-1SMTP\s0 service configuration.
Use \*(L"Debug => 1\*(R" option under \fInew()\fR to see if disabled.
.ie n .IP "help ( [ $subject ] )" 4
.el .IP "help ( [ \f(CW$subject\fR ] )" 4
.IX Item "help ( [ $subject ] )"
Request help text from the server. Returns the text or undef upon failure
.IP "quit ()" 4
.IX Item "quit ()"
Send the \s-1QUIT\s0 command to the remote \s-1SMTP\s0 server and close the socket connection.
.SH "ADDRESSES"
.IX Header "ADDRESSES"
Net::SMTP attempts to \s-1DWIM\s0 with addresses that are passed. For
example an application might extract The From: line from an email
and pass that to \fImail()\fR. While this may work, it is not reccomended.
The application should really use a module like Mail::Address
to extract the mail address and pass that.
.PP
If \f(CW\*(C`ExactAddresses\*(C'\fR is passed to the contructor, then addresses
should be a valid rfc2821\-quoted address, although Net::SMTP will
accept accept the address surrounded by angle brackets.
.PP
.Vb 3
\& funny user@domain      WRONG
\& "funny user"@domain    RIGHT, recommended
\& <"funny user"@domain>  OK
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Net::Cmd
.SH "AUTHOR"
.IX Header "AUTHOR"
Graham Barr <gbarr@pobox.com>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 1995\-2004 Graham Barr. All rights reserved.
This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.