diff options
Diffstat (limited to 'upstream/archlinux/man3/Net::POP3.3perl')
| -rw-r--r-- | upstream/archlinux/man3/Net::POP3.3perl | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/upstream/archlinux/man3/Net::POP3.3perl b/upstream/archlinux/man3/Net::POP3.3perl new file mode 100644 index 00000000..03fd66f4 --- /dev/null +++ b/upstream/archlinux/man3/Net::POP3.3perl @@ -0,0 +1,324 @@ +.\" -*- 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::POP3 3perl" +.TH Net::POP3 3perl 2024-02-11 "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::POP3 \- Post Office Protocol 3 Client class (RFC1939) +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Net::POP3; +\& +\& # Constructors +\& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq); +\& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq, Timeout => 60); +\& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq, SSL => 1, Timeout => 60); +\& +\& if ($pop\->login($username, $password) > 0) { +\& my $msgnums = $pop\->list; # hashref of msgnum => size +\& foreach my $msgnum (keys %$msgnums) { +\& my $msg = $pop\->get($msgnum); +\& print @$msg; +\& $pop\->delete($msgnum); +\& } +\& } +\& +\& $pop\->quit; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This module implements a client interface to the POP3 protocol, enabling +a perl5 application to talk to POP3 servers. This documentation assumes +that you are familiar with the POP3 protocol described in RFC1939. +With IO::Socket::SSL installed it also provides support for implicit and +explicit TLS encryption, i.e. POP3S or POP3+STARTTLS. +.PP +A new Net::POP3 object must be created with the \fInew\fR method. Once +this has been done, all POP3 commands are accessed via method calls +on the object. +.PP +The Net::POP3 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::POP3 object. \f(CW$host\fR is the +name of the remote host to which an POP3 connection is required. +.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`POP3_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 +\&\fBHost\fR \- POP3 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 "host" method will return the value +which was used to connect to the host. +.Sp +\&\fBPort\fR \- port to connect to. +Default \- 110 for plain POP3 and 995 for POP3s (direct 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. +For compatibility with older versions \fBResvPort\fR can be used instead of +\&\fBLocalPort\fR. +.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 +POP3 server (default: 120) +.Sp +\&\fBDebug\fR \- Enable debugging information +.SS "Object Methods" +.IX Subsection "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::POP3\*(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 POP3 server in addition to the methods +documented here. +.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 """auth($username, $password)""" 4 +.el .IP "\f(CWauth($username, $password)\fR" 4 +.IX Item "auth($username, $password)" +Attempt SASL authentication. +.ie n .IP user($user) 4 +.el .IP \f(CWuser($user)\fR 4 +.IX Item "user($user)" +Send the USER command. +.ie n .IP pass($pass) 4 +.el .IP \f(CWpass($pass)\fR 4 +.IX Item "pass($pass)" +Send the PASS command. Returns the number of messages in the mailbox. +.ie n .IP """login([$user[, $pass]])""" 4 +.el .IP "\f(CWlogin([$user[, $pass]])\fR" 4 +.IX Item "login([$user[, $pass]])" +Send both the USER and PASS commands. If \f(CW$pass\fR is not given the +\&\f(CW\*(C`Net::POP3\*(C'\fR uses \f(CW\*(C`Net::Netrc\*(C'\fR to lookup the password using the host +and username. If the username is not specified then the current user name +will be used. +.Sp +Returns the number of messages in the mailbox. However if there are no +messages on the server the string \f(CW"0E0"\fR will be returned. This is +will give a true value in a boolean context, but zero in a numeric context. +.Sp +If there was an error authenticating the user then \fIundef\fR will be returned. +.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 """apop([$user[, $pass]])""" 4 +.el .IP "\f(CWapop([$user[, $pass]])\fR" 4 +.IX Item "apop([$user[, $pass]])" +Authenticate with the server identifying as \f(CW$user\fR with password \f(CW$pass\fR. +Similar to "login", but the password is not sent in clear text. +.Sp +To use this method you must have the Digest::MD5 or the MD5 module installed, +otherwise this method will return \fIundef\fR. +.ie n .IP banner() 4 +.el .IP \f(CWbanner()\fR 4 +.IX Item "banner()" +Return the sever's connection banner +.ie n .IP capa() 4 +.el .IP \f(CWcapa()\fR 4 +.IX Item "capa()" +Return a reference to a hash of the capabilities of the server. APOP +is added as a pseudo capability. Note that I've been unable to +find a list of the standard capability values, and some appear to +be multi-word and some are not. We make an attempt at intelligently +parsing them, but it may not be correct. +.ie n .IP capabilities() 4 +.el .IP \f(CWcapabilities()\fR 4 +.IX Item "capabilities()" +Just like capa, but only uses a cache from the last time we asked +the server, so as to avoid asking more than once. +.ie n .IP """top($msgnum[, $numlines])""" 4 +.el .IP "\f(CWtop($msgnum[, $numlines])\fR" 4 +.IX Item "top($msgnum[, $numlines])" +Get the header and the first \f(CW$numlines\fR of the body for the message +\&\f(CW$msgnum\fR. Returns a reference to an array which contains the lines of text +read from the server. +.ie n .IP list([$msgnum]) 4 +.el .IP \f(CWlist([$msgnum])\fR 4 +.IX Item "list([$msgnum])" +If called with an argument the \f(CW\*(C`list\*(C'\fR returns the size of the message +in octets. +.Sp +If called without arguments a reference to a hash is returned. The +keys will be the \f(CW$msgnum\fR's of all undeleted messages and the values will +be their size in octets. +.ie n .IP """get($msgnum[, $fh])""" 4 +.el .IP "\f(CWget($msgnum[, $fh])\fR" 4 +.IX Item "get($msgnum[, $fh])" +Get the message \f(CW$msgnum\fR from the remote mailbox. If \f(CW$fh\fR is not given +then get returns a reference to an array which contains the lines of +text read from the server. If \f(CW$fh\fR is given then the lines returned +from the server are printed to the filehandle \f(CW$fh\fR. +.ie n .IP getfh($msgnum) 4 +.el .IP \f(CWgetfh($msgnum)\fR 4 +.IX Item "getfh($msgnum)" +As per \fBget()\fR, but returns a tied filehandle. Reading from this +filehandle returns the requested message. The filehandle will return +EOF at the end of the message and should not be reused. +.ie n .IP last() 4 +.el .IP \f(CWlast()\fR 4 +.IX Item "last()" +Returns the highest \f(CW$msgnum\fR of all the messages accessed. +.ie n .IP popstat() 4 +.el .IP \f(CWpopstat()\fR 4 +.IX Item "popstat()" +Returns a list of two elements. These are the number of undeleted +elements and the size of the mbox in octets. +.ie n .IP ping($user) 4 +.el .IP \f(CWping($user)\fR 4 +.IX Item "ping($user)" +Returns a list of two elements. These are the number of new messages +and the total number of messages for \f(CW$user\fR. +.ie n .IP uidl([$msgnum]) 4 +.el .IP \f(CWuidl([$msgnum])\fR 4 +.IX Item "uidl([$msgnum])" +Returns a unique identifier for \f(CW$msgnum\fR if given. If \f(CW$msgnum\fR is not +given \f(CW\*(C`uidl\*(C'\fR returns a reference to a hash where the keys are the +message numbers and the values are the unique identifiers. +.ie n .IP delete($msgnum) 4 +.el .IP \f(CWdelete($msgnum)\fR 4 +.IX Item "delete($msgnum)" +Mark message \f(CW$msgnum\fR to be deleted from the remote mailbox. All messages +that are marked to be deleted will be removed from the remote mailbox +when the server connection closed. +.ie n .IP reset() 4 +.el .IP \f(CWreset()\fR 4 +.IX Item "reset()" +Reset the status of the remote POP3 server. This includes resetting the +status of all messages to not be deleted. +.ie n .IP quit() 4 +.el .IP \f(CWquit()\fR 4 +.IX Item "quit()" +Quit and close the connection to the remote POP3 server. Any messages marked +as deleted will be deleted from the remote mailbox. +.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 Notes +.IX Subsection "Notes" +If a \f(CW\*(C`Net::POP3\*(C'\fR object goes out of scope before \f(CW\*(C`quit\*(C'\fR method is called +then the \f(CW\*(C`reset\*(C'\fR method will called before the connection is closed. This +means that any messages marked to be deleted will not be. +.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::Netrc, +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. |