Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 496 insertions, 0 deletions

diff --git a/upstream/debian-unstable/man3/Net::SMTP.3perl b/upstream/debian-unstable/man3/Net::SMTP.3perl
new file mode 100644
index 00000000..69e608c5
--- /dev/null
+++ b/upstream/debian-unstable/man3/Net::SMTP.3perl
@@ -0,0 +1,496 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" 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
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'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 >0, 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.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Net::SMTP 3perl"
+.TH Net::SMTP 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" 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
+Net::SMTP \- Simple Mail Transfer Protocol Client
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.Vb 1
+\&    use Net::SMTP;
+\&
+\&    # Constructors
+\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
+\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq, Timeout => 60);
+.Ve
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This module implements a client interface to the SMTP and ESMTP
+protocol, enabling a perl5 application to talk to SMTP servers. This
+documentation assumes that you are familiar with the concepts of the
+SMTP protocol described in RFC2821.
+With IO::Socket::SSL installed it also provides support for implicit and
+explicit TLS encryption, i.e. SMTPS or SMTP+STARTTLS.
+.PP
+The Net::SMTP class is a subclass of Net::Cmd and (depending on avaibility) of
+IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
+.SS "Class Methods"
+.IX Subsection "Class Methods"
+.ie n .IP """new([$host][, %options])""" 4
+.el .IP "\f(CWnew([$host][, %options])\fR" 4
+.IX Item "new([$host][, %options])"
+This is the constructor for a new Net::SMTP object. \f(CW$host\fR is the
+name of the remote host to which an SMTP connection is required.
+.Sp
+On failure \f(CW\*(C`undef\*(C'\fR will be returned and \f(CW$@\fR will contain the reason
+for the failure.
+.Sp
+\&\f(CW$host\fR is optional. If \f(CW$host\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%options\fR are passed in a hash like fashion, using key and value pairs.
+Possible options are:
+.Sp
+\&\fBHello\fR \- SMTP 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
+\&\fBSendHello\fR \- If false then the EHLO (or HELO) command that is normally sent
+when constructing the object will not be sent. In that case the command will
+have to be sent manually by calling \f(CWhello()\fR instead.
+.Sp
+\&\fBHost\fR \- SMTP host to connect to. It may be a single scalar (hostname[:port]),
+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 "host" method will return the value
+which was used to connect to the host.
+Format \- \f(CW\*(C`PeerHost\*(C'\fR from IO::Socket::INET new method.
+.Sp
+\&\fBPort\fR \- port to connect to.
+Default \- 25 for plain SMTP and 465 for immediate SSL.
+.Sp
+\&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later
+upgrade with \f(CW\*(C`starttls\*(C'\fR.
+You can use SSL arguments as documented in IO::Socket::SSL, but it will
+usually use the right arguments already.
+.Sp
+\&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
+to IO::Socket to allow binding the socket to a specific local address and port.
+.Sp
+\&\fBDomain\fR \- This parameter is passed directly to IO::Socket and makes it
+possible to enforce IPv4 connections even if IO::Socket::IP is used as super
+class. Alternatively \fBFamily\fR can be used.
+.Sp
+\&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
+SMTP server (default: 120)
+.Sp
+\&\fBExactAddresses\fR \- If true then all \f(CW$address\fR arguments must be as
+defined by \f(CW\*(C`addr\-spec\*(C'\fR in RFC2822. 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(\*(Aqmailhost\*(Aq,
+\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
+\&                           Timeout => 30,
+\&                           Debug   => 1,
+\&                          );
+\&
+\&    # the same
+\&    $smtp = Net::SMTP\->new(
+\&                           Host => \*(Aqmailhost\*(Aq,
+\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
+\&                           Timeout => 30,
+\&                           Debug   => 1,
+\&                          );
+\&
+\&    # the same with direct SSL
+\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq,
+\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
+\&                           Timeout => 30,
+\&                           Debug   => 1,
+\&                           SSL     => 1,
+\&                          );
+\&
+\&    # Connect to the default server from Net::config
+\&    $smtp = Net::SMTP\->new(
+\&                           Hello => \*(Aqmy.mail.domain\*(Aq,
+\&                           Timeout => 30,
+\&                          );
+.Ve
+.SH "Object Methods"
+.IX Header "Object 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.
+.PP
+\&\f(CW\*(C`Net::SMTP\*(C'\fR inherits from \f(CW\*(C`Net::Cmd\*(C'\fR so methods defined in \f(CW\*(C`Net::Cmd\*(C'\fR may
+be used to send commands to the remote SMTP server in addition to the methods
+documented here.
+.ie n .IP banner() 4
+.el .IP \f(CWbanner()\fR 4
+.IX Item "banner()"
+Returns the banner message which the server replied with when the
+initial connection was made.
+.ie n .IP domain() 4
+.el .IP \f(CWdomain()\fR 4
+.IX Item "domain()"
+Returns the domain that the remote SMTP server identified itself as during
+connection.
+.ie n .IP hello($domain) 4
+.el .IP \f(CWhello($domain)\fR 4
+.IX Item "hello($domain)"
+Tell the remote server the mail domain which you are in using the EHLO
+command (or HELO if EHLO fails).  Since this method is invoked
+automatically when the Net::SMTP object is constructed the user should
+normally not have to call it manually.
+.ie n .IP host() 4
+.el .IP \f(CWhost()\fR 4
+.IX Item "host()"
+Returns the value used by the constructor, and passed to IO::Socket::INET,
+to connect to the host.
+.ie n .IP etrn($domain) 4
+.el .IP \f(CWetrn($domain)\fR 4
+.IX Item "etrn($domain)"
+Request a queue run for the \f(CW$domain\fR given.
+.ie n .IP starttls(%sslargs) 4
+.el .IP \f(CWstarttls(%sslargs)\fR 4
+.IX Item "starttls(%sslargs)"
+Upgrade existing plain connection to SSL.
+You can use SSL arguments as documented in IO::Socket::SSL, but it will
+usually use the right arguments already.
+.ie n .IP """auth($username, $password)""" 4
+.el .IP "\f(CWauth($username, $password)\fR" 4
+.IX Item "auth($username, $password)"
+.PD 0
+.ie n .IP auth($sasl) 4
+.el .IP \f(CWauth($sasl)\fR 4
+.IX Item "auth($sasl)"
+.PD
+Attempt SASL authentication. Requires Authen::SASL module. The first form
+constructs a new Authen::SASL object using the given username and password;
+the second form uses the given Authen::SASL object.
+.ie n .IP """mail($address[, %options])""" 4
+.el .IP "\f(CWmail($address[, %options])\fR" 4
+.IX Item "mail($address[, %options])"
+.PD 0
+.ie n .IP send($address) 4
+.el .IP \f(CWsend($address)\fR 4
+.IX Item "send($address)"
+.ie n .IP send_or_mail($address) 4
+.el .IP \f(CWsend_or_mail($address)\fR 4
+.IX Item "send_or_mail($address)"
+.ie n .IP send_and_mail($address) 4
+.el .IP \f(CWsend_and_mail($address)\fR 4
+.IX Item "send_and_mail($address)"
+.PD
+Send the appropriate command to the server MAIL, SEND, SOML or SAML. \f(CW$address\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 take some additional ESMTP \f(CW%options\fR which is passed
+in hash like fashion, using key and value pairs.  Possible options are:
+.Sp
+.Vb 8
+\& Size        => <bytes>
+\& Return      => "FULL" | "HDRS"
+\& Bits        => "7" | "8" | "binary"
+\& Transaction => <ADDRESS>
+\& Envelope    => <ENVID>     # xtext\-encodes its argument
+\& ENVID       => <ENVID>     # similar to Envelope, but expects argument encoded
+\& XVERP       => 1
+\& AUTH        => <submitter> # encoded address according to RFC 2554
+.Ve
+.Sp
+The \f(CW\*(C`Return\*(C'\fR and \f(CW\*(C`Envelope\*(C'\fR parameters are used for DSN (Delivery
+Status Notification).
+.Sp
+The submitter address in \f(CW\*(C`AUTH\*(C'\fR option is expected to be in a format as
+required by RFC 2554, in an RFC2821\-quoted form and xtext-encoded, or <> .
+.ie n .IP reset() 4
+.el .IP \f(CWreset()\fR 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.
+.ie n .IP """recipient($address[, $address[, ...]][, %options])""" 4
+.el .IP "\f(CWrecipient($address[, $address[, ...]][, %options])\fR" 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 \f(CW%options\fR as an
+anonymous hash using key and value pairs.  Possible options are:
+.Sp
+.Vb 3
+\&  Notify  => [\*(AqNEVER\*(Aq] or [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq]  (see below)
+\&  ORcpt   => <ORCPT>
+\&  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 => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 });  # Good
+\&  @goodrecips=$smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq], SkipBad => 1 });  # Good
+\&  $smtp\->recipient("$recipient,$recipient2"); # BAD
+.Ve
+.Sp
+Notify is used to request Delivery Status Notifications (DSNs), but your
+SMTP/ESMTP service may not respect this request depending upon its version and
+your site's SMTP configuration.
+.Sp
+Leaving out the Notify option usually defaults an SMTP service to its default
+behavior equivalent to ['FAILURE'] notifications only, but again this may be
+dependent upon your site's SMTP configuration.
+.Sp
+The NEVER keyword must appear by itself if used within the Notify option and "requests
+that a DSN not be returned to the sender under any conditions."
+.Sp
+.Vb 1
+\&  {Notify => [\*(AqNEVER\*(Aq]}
+\&
+\&  $smtp\->recipient(@recipients, { Notify => [\*(AqNEVER\*(Aq], SkipBad => 1 });  # Good
+.Ve
+.Sp
+You may use any combination of these three values 'SUCCESS','FAILURE','DELAY' in
+the anonymous array reference as defined by RFC3461 (see
+<https://www.ietf.org/rfc/rfc3461.txt> for more information.  Note: quotations
+in this topic from same.).
+.Sp
+A Notify parameter of 'SUCCESS' or 'FAILURE' "requests that a DSN be issued on
+successful delivery or delivery failure, respectively."
+.Sp
+A Notify parameter of 'DELAY' "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 (MTA) at which the message is delayed), but the final delivery status
+(whether successful or failure) cannot be determined.  The absence of the DELAY
+keyword in a NOTIFY parameter requests that a "delayed" DSN NOT be issued under
+any conditions."
+.Sp
+.Vb 1
+\&  {Notify => [\*(AqSUCCESS\*(Aq,\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq]}
+\&
+\&  $smtp\->recipient(@recipients, { Notify => [\*(AqFAILURE\*(Aq,\*(AqDELAY\*(Aq], SkipBad => 1 });  # Good
+.Ve
+.Sp
+ORcpt is also part of the SMTP DSN extension according to RFC3461.
+It is used to pass along the original recipient that the mail was first
+sent to.  The machine that generates a DSN will use this address to inform
+the sender, because he can't know if recipients get rewritten by mail servers.
+It is expected to be in a format as required by RFC3461, xtext-encoded.
+.ie n .IP """to($address[, $address[, ...]])""" 4
+.el .IP "\f(CWto($address[, $address[, ...]])\fR" 4
+.IX Item "to($address[, $address[, ...]])"
+.PD 0
+.ie n .IP """cc($address[, $address[, ...]])""" 4
+.el .IP "\f(CWcc($address[, $address[, ...]])\fR" 4
+.IX Item "cc($address[, $address[, ...]])"
+.ie n .IP """bcc($address[, $address[, ...]])""" 4
+.el .IP "\f(CWbcc($address[, $address[, ...]])\fR" 4
+.IX Item "bcc($address[, $address[, ...]])"
+.PD
+Synonyms for \f(CW\*(C`recipient\*(C'\fR.
+.ie n .IP data([$data]) 4
+.el .IP \f(CWdata([$data])\fR 4
+.IX Item "data([$data])"
+Initiate the sending of the data from the current message.
+.Sp
+\&\f(CW$data\fR may be a reference to a list or a list and must be encoded by the
+caller to octets of whatever encoding is required, e.g. by using the Encode
+module's \f(CWencode()\fR function.
+.Sp
+If specified the contents of \f(CW$data\fR and a termination string \f(CW".\er\en"\fR is
+sent to the server. The result will be true if the data was accepted.
+.Sp
+If \f(CW$data\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.
+.ie n .IP bdat($data) 4
+.el .IP \f(CWbdat($data)\fR 4
+.IX Item "bdat($data)"
+.PD 0
+.ie n .IP bdatlast($data) 4
+.el .IP \f(CWbdatlast($data)\fR 4
+.IX Item "bdatlast($data)"
+.PD
+Use the alternate \f(CW$data\fR command "BDAT" of the data chunking service extension
+defined in RFC1830 for efficiently sending large MIME messages.
+.ie n .IP expand($address) 4
+.el .IP \f(CWexpand($address)\fR 4
+.IX Item "expand($address)"
+Request the server to expand the given address Returns an array
+which contains the text read from the server.
+.ie n .IP verify($address) 4
+.el .IP \f(CWverify($address)\fR 4
+.IX Item "verify($address)"
+Verify that \f(CW$address\fR is a legitimate mailing address.
+.Sp
+Most sites usually disable this feature in their SMTP service configuration.
+Use "Debug => 1" option under \fBnew()\fR to see if disabled.
+.ie n .IP help([$subject]) 4
+.el .IP \f(CWhelp([$subject])\fR 4
+.IX Item "help([$subject])"
+Request help text from the server. Returns the text or undef upon failure
+.ie n .IP quit() 4
+.el .IP \f(CWquit()\fR 4
+.IX Item "quit()"
+Send the QUIT command to the remote SMTP server and close the socket connection.
+.ie n .IP can_inet6() 4
+.el .IP \f(CWcan_inet6()\fR 4
+.IX Item "can_inet6()"
+Returns whether we can use IPv6.
+.ie n .IP can_ssl() 4
+.el .IP \f(CWcan_ssl()\fR 4
+.IX Item "can_ssl()"
+Returns whether we can use SSL.
+.SS Addresses
+.IX Subsection "Addresses"
+Net::SMTP attempts to DWIM with addresses that are passed. For
+example an application might extract The From: line from an email
+and pass that to \fBmail()\fR. While this may work, it is not recommended.
+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 constructor, then addresses
+should be a valid rfc2821\-quoted address, although Net::SMTP will
+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 EXAMPLES
+.IX Header "EXAMPLES"
+This example prints the mail domain name of the SMTP server known as mailhost:
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl \-w
+\&
+\&    use Net::SMTP;
+\&
+\&    $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
+\&    print $smtp\->domain,"\en";
+\&    $smtp\->quit;
+.Ve
+.PP
+This example sends a small message to the postmaster at the SMTP server
+known as mailhost:
+.PP
+.Vb 1
+\&    #!/usr/local/bin/perl \-w
+\&
+\&    use Net::SMTP;
+\&
+\&    my $smtp = Net::SMTP\->new(\*(Aqmailhost\*(Aq);
+\&
+\&    $smtp\->mail($ENV{USER});
+\&    if ($smtp\->to(\*(Aqpostmaster\*(Aq)) {
+\&     $smtp\->data();
+\&     $smtp\->datasend("To: postmaster\en");
+\&     $smtp\->datasend("\en");
+\&     $smtp\->datasend("A simple test message\en");
+\&     $smtp\->dataend();
+\&    } else {
+\&     print "Error: ", $smtp\->message();
+\&    }
+\&
+\&    $smtp\->quit;
+.Ve
+.SH EXPORTS
+.IX Header "EXPORTS"
+\&\fINone\fR.
+.SH "KNOWN BUGS"
+.IX Header "KNOWN BUGS"
+See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Net::Cmd,
+IO::Socket::SSL.
+.SH AUTHOR
+.IX Header "AUTHOR"
+Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
+.PP
+Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
+libnet as of version 1.22_02.
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright (C) 1995\-2004 Graham Barr.  All rights reserved.
+.PP
+Copyright (C) 2013\-2016, 2020 Steve Hay.  All rights reserved.
+.SH LICENCE
+.IX Header "LICENCE"
+This module is free software; you can redistribute it and/or modify it under the
+same terms as Perl itself, i.e. under the terms of either the GNU General Public
+License or the Artistic License, as specified in the \fILICENCE\fR file.
+.SH VERSION
+.IX Header "VERSION"
+Version 3.15
+.SH DATE
+.IX Header "DATE"
+20 March 2023
+.SH HISTORY
+.IX Header "HISTORY"
+See the \fIChanges\fR file.