Debian Codegraph @

upstream/debian-unstable/man3/Net::POP3.3perl

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