Debian Codegraph @

upstream/mageia-cauldron/man3pm/Net::POP3.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Net::POP3 3pm"
61 .TH Net::POP3 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Net::POP3 \- Post Office Protocol 3 Client class (RFC1939)
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use Net::POP3;
72 \&
73 \& # Constructors
74 \& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq);
75 \& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq, Timeout => 60);
76 \& $pop = Net::POP3\->new(\*(Aqpop3host\*(Aq, SSL => 1, Timeout => 60);
77 \&
78 \& if ($pop\->login($username, $password) > 0) {
79 \& my $msgnums = $pop\->list; # hashref of msgnum => size
80 \& foreach my $msgnum (keys %$msgnums) {
81 \& my $msg = $pop\->get($msgnum);
82 \& print @$msg;
83 \& $pop\->delete($msgnum);
84 \& }
85 \& }
86 \&
87 \& $pop\->quit;
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 This module implements a client interface to the POP3 protocol, enabling
92 a perl5 application to talk to POP3 servers. This documentation assumes
93 that you are familiar with the POP3 protocol described in RFC1939.
94 With IO::Socket::SSL installed it also provides support for implicit and
95 explicit TLS encryption, i.e. POP3S or POP3+STARTTLS.
96 .PP
97 A new Net::POP3 object must be created with the \fInew\fR method. Once
98 this has been done, all POP3 commands are accessed via method calls
99 on the object.
100 .PP
101 The Net::POP3 class is a subclass of Net::Cmd and (depending on avaibility) of
102 IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
103 .SS "Class Methods"
104 .IX Subsection "Class Methods"
105 .ie n .IP """new([$host][, %options])""" 4
106 .el .IP "\f(CWnew([$host][, %options])\fR" 4
107 .IX Item "new([$host][, %options])"
108 This is the constructor for a new Net::POP3 object. \f(CW$host\fR is the
109 name of the remote host to which an POP3 connection is required.
110 .Sp
111 \&\f(CW$host\fR is optional. If \f(CW$host\fR is not given then it may instead be
112 passed as the \f(CW\*(C`Host\*(C'\fR option described below. If neither is given then
113 the \f(CW\*(C`POP3_Hosts\*(C'\fR specified in \f(CW\*(C`Net::Config\*(C'\fR will be used.
114 .Sp
115 \&\f(CW%options\fR are passed in a hash like fashion, using key and value pairs.
116 Possible options are:
117 .Sp
118 \&\fBHost\fR \- POP3 host to connect to. It may be a single scalar, as defined for
119 the \f(CW\*(C`PeerAddr\*(C'\fR option in IO::Socket::INET, or a reference to
120 an array with hosts to try in turn. The "host" method will return the value
121 which was used to connect to the host.
122 .Sp
123 \&\fBPort\fR \- port to connect to.
124 Default \- 110 for plain POP3 and 995 for POP3s (direct SSL).
125 .Sp
126 \&\fBSSL\fR \- If the connection should be done from start with SSL, contrary to later
127 upgrade with \f(CW\*(C`starttls\*(C'\fR.
128 You can use SSL arguments as documented in IO::Socket::SSL, but it will
129 usually use the right arguments already.
130 .Sp
131 \&\fBLocalAddr\fR and \fBLocalPort\fR \- These parameters are passed directly
132 to IO::Socket to allow binding the socket to a specific local address and port.
133 For compatibility with older versions \fBResvPort\fR can be used instead of
134 \&\fBLocalPort\fR.
135 .Sp
136 \&\fBDomain\fR \- This parameter is passed directly to IO::Socket and makes it
137 possible to enforce IPv4 connections even if IO::Socket::IP is used as super
138 class. Alternatively \fBFamily\fR can be used.
139 .Sp
140 \&\fBTimeout\fR \- Maximum time, in seconds, to wait for a response from the
141 POP3 server (default: 120)
142 .Sp
143 \&\fBDebug\fR \- Enable debugging information
144 .SS "Object Methods"
145 .IX Subsection "Object Methods"
146 Unless otherwise stated all methods return either a \fItrue\fR or \fIfalse\fR
147 value, with \fItrue\fR meaning that the operation was a success. When a method
148 states that it returns a value, failure will be returned as \fIundef\fR or an
149 empty list.
150 .PP
151 \&\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
152 be used to send commands to the remote POP3 server in addition to the methods
153 documented here.
154 .ie n .IP host() 4
155 .el .IP \f(CWhost()\fR 4
156 .IX Item "host()"
157 Returns the value used by the constructor, and passed to IO::Socket::INET,
158 to connect to the host.
159 .ie n .IP """auth($username, $password)""" 4
160 .el .IP "\f(CWauth($username, $password)\fR" 4
161 .IX Item "auth($username, $password)"
162 Attempt SASL authentication.
163 .ie n .IP user($user) 4
164 .el .IP \f(CWuser($user)\fR 4
165 .IX Item "user($user)"
166 Send the USER command.
167 .ie n .IP pass($pass) 4
168 .el .IP \f(CWpass($pass)\fR 4
169 .IX Item "pass($pass)"
170 Send the PASS command. Returns the number of messages in the mailbox.
171 .ie n .IP """login([$user[, $pass]])""" 4
172 .el .IP "\f(CWlogin([$user[, $pass]])\fR" 4
173 .IX Item "login([$user[, $pass]])"
174 Send both the USER and PASS commands. If \f(CW$pass\fR is not given the
175 \&\f(CW\*(C`Net::POP3\*(C'\fR uses \f(CW\*(C`Net::Netrc\*(C'\fR to lookup the password using the host
176 and username. If the username is not specified then the current user name
177 will be used.
178 .Sp
179 Returns the number of messages in the mailbox. However if there are no
180 messages on the server the string \f(CW"0E0"\fR will be returned. This is
181 will give a true value in a boolean context, but zero in a numeric context.
182 .Sp
183 If there was an error authenticating the user then \fIundef\fR will be returned.
184 .ie n .IP starttls(%sslargs) 4
185 .el .IP \f(CWstarttls(%sslargs)\fR 4
186 .IX Item "starttls(%sslargs)"
187 Upgrade existing plain connection to SSL.
188 You can use SSL arguments as documented in IO::Socket::SSL, but it will
189 usually use the right arguments already.
190 .ie n .IP """apop([$user[, $pass]])""" 4
191 .el .IP "\f(CWapop([$user[, $pass]])\fR" 4
192 .IX Item "apop([$user[, $pass]])"
193 Authenticate with the server identifying as \f(CW$user\fR with password \f(CW$pass\fR.
194 Similar to "login", but the password is not sent in clear text.
195 .Sp
196 To use this method you must have the Digest::MD5 or the MD5 module installed,
197 otherwise this method will return \fIundef\fR.
198 .ie n .IP banner() 4
199 .el .IP \f(CWbanner()\fR 4
200 .IX Item "banner()"
201 Return the sever\*(Aqs connection banner
202 .ie n .IP capa() 4
203 .el .IP \f(CWcapa()\fR 4
204 .IX Item "capa()"
205 Return a reference to a hash of the capabilities of the server. APOP
206 is added as a pseudo capability. Note that I\*(Aqve been unable to
207 find a list of the standard capability values, and some appear to
208 be multi\-word and some are not. We make an attempt at intelligently
209 parsing them, but it may not be correct.
210 .ie n .IP capabilities() 4
211 .el .IP \f(CWcapabilities()\fR 4
212 .IX Item "capabilities()"
213 Just like capa, but only uses a cache from the last time we asked
214 the server, so as to avoid asking more than once.
215 .ie n .IP """top($msgnum[, $numlines])""" 4
216 .el .IP "\f(CWtop($msgnum[, $numlines])\fR" 4
217 .IX Item "top($msgnum[, $numlines])"
218 Get the header and the first \f(CW$numlines\fR of the body for the message
219 \&\f(CW$msgnum\fR. Returns a reference to an array which contains the lines of text
220 read from the server.
221 .ie n .IP list([$msgnum]) 4
222 .el .IP \f(CWlist([$msgnum])\fR 4
223 .IX Item "list([$msgnum])"
224 If called with an argument the \f(CW\*(C`list\*(C'\fR returns the size of the message
225 in octets.
226 .Sp
227 If called without arguments a reference to a hash is returned. The
228 keys will be the \f(CW$msgnum\fR\*(Aqs of all undeleted messages and the values will
229 be their size in octets.
230 .ie n .IP """get($msgnum[, $fh])""" 4
231 .el .IP "\f(CWget($msgnum[, $fh])\fR" 4
232 .IX Item "get($msgnum[, $fh])"
233 Get the message \f(CW$msgnum\fR from the remote mailbox. If \f(CW$fh\fR is not given
234 then get returns a reference to an array which contains the lines of
235 text read from the server. If \f(CW$fh\fR is given then the lines returned
236 from the server are printed to the filehandle \f(CW$fh\fR.
237 .ie n .IP getfh($msgnum) 4
238 .el .IP \f(CWgetfh($msgnum)\fR 4
239 .IX Item "getfh($msgnum)"
240 As per \fBget()\fR, but returns a tied filehandle. Reading from this
241 filehandle returns the requested message. The filehandle will return
242 EOF at the end of the message and should not be reused.
243 .ie n .IP last() 4
244 .el .IP \f(CWlast()\fR 4
245 .IX Item "last()"
246 Returns the highest \f(CW$msgnum\fR of all the messages accessed.
247 .ie n .IP popstat() 4
248 .el .IP \f(CWpopstat()\fR 4
249 .IX Item "popstat()"
250 Returns a list of two elements. These are the number of undeleted
251 elements and the size of the mbox in octets.
252 .ie n .IP ping($user) 4
253 .el .IP \f(CWping($user)\fR 4
254 .IX Item "ping($user)"
255 Returns a list of two elements. These are the number of new messages
256 and the total number of messages for \f(CW$user\fR.
257 .ie n .IP uidl([$msgnum]) 4
258 .el .IP \f(CWuidl([$msgnum])\fR 4
259 .IX Item "uidl([$msgnum])"
260 Returns a unique identifier for \f(CW$msgnum\fR if given. If \f(CW$msgnum\fR is not
261 given \f(CW\*(C`uidl\*(C'\fR returns a reference to a hash where the keys are the
262 message numbers and the values are the unique identifiers.
263 .ie n .IP delete($msgnum) 4
264 .el .IP \f(CWdelete($msgnum)\fR 4
265 .IX Item "delete($msgnum)"
266 Mark message \f(CW$msgnum\fR to be deleted from the remote mailbox. All messages
267 that are marked to be deleted will be removed from the remote mailbox
268 when the server connection closed.
269 .ie n .IP reset() 4
270 .el .IP \f(CWreset()\fR 4
271 .IX Item "reset()"
272 Reset the status of the remote POP3 server. This includes resetting the
273 status of all messages to not be deleted.
274 .ie n .IP quit() 4
275 .el .IP \f(CWquit()\fR 4
276 .IX Item "quit()"
277 Quit and close the connection to the remote POP3 server. Any messages marked
278 as deleted will be deleted from the remote mailbox.
279 .ie n .IP can_inet6() 4
280 .el .IP \f(CWcan_inet6()\fR 4
281 .IX Item "can_inet6()"
282 Returns whether we can use IPv6.
283 .ie n .IP can_ssl() 4
284 .el .IP \f(CWcan_ssl()\fR 4
285 .IX Item "can_ssl()"
286 Returns whether we can use SSL.
287 .SS Notes
288 .IX Subsection "Notes"
289 If a \f(CW\*(C`Net::POP3\*(C'\fR object goes out of scope before \f(CW\*(C`quit\*(C'\fR method is called
290 then the \f(CW\*(C`reset\*(C'\fR method will called before the connection is closed. This
291 means that any messages marked to be deleted will not be.
292 .SH EXPORTS
293 .IX Header "EXPORTS"
294 \&\fINone\fR.
295 .SH "KNOWN BUGS"
296 .IX Header "KNOWN BUGS"
297 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
298 .SH "SEE ALSO"
299 .IX Header "SEE ALSO"
300 Net::Netrc,
301 Net::Cmd,
302 IO::Socket::SSL.
303 .SH AUTHOR
304 .IX Header "AUTHOR"
305 Graham Barr <[email protected] <mailto:[email protected]>>.
306 .PP
307 Steve Hay <[email protected] <mailto:[email protected]>> is now maintaining
308 libnet as of version 1.22_02.
309 .SH COPYRIGHT
310 .IX Header "COPYRIGHT"
311 Copyright (C) 1995\-2004 Graham Barr. All rights reserved.
312 .PP
313 Copyright (C) 2013\-2016, 2020 Steve Hay. All rights reserved.
314 .SH LICENCE
315 .IX Header "LICENCE"
316 This module is free software; you can redistribute it and/or modify it under the
317 same terms as Perl itself, i.e. under the terms of either the GNU General Public
318 License or the Artistic License, as specified in the \fILICENCE\fR file.
319 .SH VERSION
320 .IX Header "VERSION"
321 Version 3.15
322 .SH DATE
323 .IX Header "DATE"
324 20 March 2023
325 .SH HISTORY
326 .IX Header "HISTORY"
327 See the \fIChanges\fR file.