forked from soulwing/popclient
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathpopclient.html
568 lines (424 loc) · 17.6 KB
/
popclient.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
<!-- Creator : groff version 1.19.2 -->
<!-- CreationDate: Thu Jan 12 08:32:27 2017 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; }
pre { margin-top: 0; margin-bottom: 0; }
table { margin-top: 0; margin-bottom: 0; }
</style>
<title>popclient</title>
</head>
<body>
<h1 align=center>popclient</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#OPTIONS">OPTIONS</a><br>
<a href="#PROTOCOL SELECTION">PROTOCOL SELECTION</a><br>
<a href="#USER AUTHENTICATION">USER AUTHENTICATION</a><br>
<a href="#OUTPUT OPTIONS">OUTPUT OPTIONS</a><br>
<a href="#EXIT CODES">EXIT CODES</a><br>
<a href="#AUTHOR">AUTHOR</a><br>
<a href="#BUGS">BUGS</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<hr>
<a name="NAME"></a>
<h2>NAME</h2>
<p style="margin-left:11%; margin-top: 1em">popclient
− retrieve mail from a mailserver using Post Office
Protocol.</p>
<a name="SYNOPSIS"></a>
<h2>SYNOPSIS</h2>
<p style="margin-left:11%; margin-top: 1em"><b>popclient</b>
[<b>-2</b> | <b>-3</b>] [<b>-Vksv</b>] [<b>-u</b>
<i>server-userid</i>] [<b>-p</b> <i>server-password</i>]
<br>
[<b>-f</b> <i>remote-folder</i>] [<b>-c</b> | <b>-o</b>
<i>local-folder</i>] <i>host</i></p>
<a name="DESCRIPTION"></a>
<h2>DESCRIPTION</h2>
<p style="margin-left:11%; margin-top: 1em"><i>popclient</i>
is a Post Office Protocol compliant mail retrieval client
which supports both POP2 (as specified in RFC 937) and POP3
(RFC 1225).</p>
<p style="margin-left:11%; margin-top: 1em">Typically,
<i>popclient</i> will be used to download mail in batch from
the remote mailserver specified by <i>host</i> to a mail
folder on the local disk. The retrieved mail will then be
manipulated using a local mail reader, such as <i>mail</i>
or <i>elm.</i></p>
<p style="margin-left:11%; margin-top: 1em">To facilitate
the use of <i>popclient</i> in scripts, pipelines, etc, it
returns an appropriate exit code upon termination -- see
EXIT CODES below.</p>
<a name="OPTIONS"></a>
<h2>OPTIONS</h2>
<table width="100%" border=0 rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−2</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Use Post Office
Protocol version 2 (POP2).</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−3</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Use Post Office
Protocol version 3 (POP3).</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−k</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Keep messages in
folder on remote mailserver. Normally, messages are deleted
from the folder on the mailserver after they have been
retrieved. Specifying <b>−k</b> causes retrieved
messages to remain in your folder on the mailserver.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−s</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Silent mode.
Suppresses all progress/status messages that are normally
echoed to stderr during a POP connection. If both the
<b>−s</b> and <b>−v</b> options are specified,
the <b>−v</b> option takes precedence.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−v</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Verbose mode. All
control messages passed between <i>popclient</i> and the
mailserver are echoed to stderr. Specifying <b>−v</b>
causes normal progress/status messages which would be
redundant or meaningless to be modified or omitted.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−u</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Specifies the user
idenfication to be used when logging-in to the mailserver.
The appropriate user identification is both server and user
dependent. Default is your login name on the machine that is
running <i>popclient.</i> See USER AUTHENTICATION below for
a complete description.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−p</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Specifies the
password to be used when logging-in to the mailserver. The
appropriate password is both server and user dependent. If
the <b>−p</b> option is not used to specify a
password, you will be prompted for a password before the
connection to the mailserver is established. See USER
AUTHENTICATION below for a complete description.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−f</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Causes an alternate
mail folder on the mailserver to be retrieved. The syntax of
the folder name is server dependent, as is the default
behavior when no folder is specified. Fortunately, most POP
servers have a reasonable default behavior, so use of this
option should be limited to fairly specialized applications.
POP3 does not provide a folder specification in the
protocol. If the <b>−f</b> option is used in
conjunction with the <b>−3</b> option, the remote
folder specification is ignored.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−o</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Causes retrieved
messages to be appended to an alternate mail folder on the
local disk. When neither <b>−o</b> nor <b>−c</b>
is specified, retrieved messages are appended to the system
default mail folder. See OUTPUT OPTIONS below for a complete
description.</p> </td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−c</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Causes retrieved
messages to be written to stdout instead of a mail folder.
See OUTPUT OPTIONS below for a complete description. You may
not specify both the <b>−c</b> and <b>−o</b>
options on the same command line.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="3%">
<p style="margin-top: 1em" valign="top">−V</p></td>
<td width="8%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Displays the
version information for your copy of <i>popclient.</i> If
you specify the <b>−V</b> option, all other options
are ignored and no POP connection is made.</p></td>
</table>
<a name="PROTOCOL SELECTION"></a>
<h2>PROTOCOL SELECTION</h2>
<p style="margin-left:11%; margin-top: 1em">The selection
of the correct Post Office Protocol (POP2 or POP3) depends
upon the configuration of the mailserver from which you
retrieve your mail. The system adminstrator who installed
<i>popclient</i> on your system should have chosen an
appropriate default protocol for your mailserver. If you get
the message ’Connection refused’ when using the
default protocol, try specifying <b>−2</b> or
<b>−3</b> to select a different protocol. If the
’Connection refused’ message persists regardless
of the protocol selected, it is likely that your mailserver
is not running a POP compliant mail service.</p>
<a name="USER AUTHENTICATION"></a>
<h2>USER AUTHENTICATION</h2>
<p style="margin-left:11%; margin-top: 1em">User
authentication in <i>popclient</i> is very much like the
authentication mechanism of <i>ftp(1).</i> The correct
user-id and password depend upon the underlying security
system at the mailserver.</p>
<p style="margin-left:11%; margin-top: 1em">If the
mailserver is a Unix machine on which you have an ordinary
user account, your regular login name and password are used
with <i>popclient.</i> If you use the same login name on
both the server and the client machines, you needn’t
worry about specifying a user-id with the <b>−u</b>
option −− the default behavior will use your
login name on the client machine as the user-id on the
server machine. If you use a different login name on the
server machine, specify that login name with the
<b>−u</b> option. e.g. if your login name is
’jsmith’ on a machine named
’mailgrunt’, you would start <i>popclient</i> as
follows:</p>
<p style="margin-left:22%; margin-top: 1em">popclient -u
jsmith mailgrunt</p>
<p style="margin-left:11%; margin-top: 1em">The default
behavior of <i>popclient</i> is to prompt you for your
mailserver password before the POP connection is
established. This is the safest way to use <i>popclient</i>
and ensures that your password will not be compromised. You
may also specify your password using the <b>−p</b>
option. This is convenient when using <i>popclient</i> with
automated scripts, but it may result in your password being
exposed to prying eyes −− be careful! Regardless
of how your password is specified it is never stored in
shared memory segments, or left unencrypted in the core
image when <i>popclient</i> terminates. Continuing the
preceding example, suppose your password on
´mailgrunt’ is ’Gr8PassWd’. The
syntax would be:</p>
<p style="margin-left:22%; margin-top: 1em">popclient -u
jsmith -p Gr8PassWd mailgrunt</p>
<p style="margin-left:11%; margin-top: 1em">On mailservers
that do not provide ordinary user accounts, your user-id and
password are usually assigned by the server administrator
when you apply for a mailbox on the server. Contact your
server administrator if you don’t know the correct
user-id and password for your mailbox account.</p>
<a name="OUTPUT OPTIONS"></a>
<h2>OUTPUT OPTIONS</h2>
<p style="margin-left:11%; margin-top: 1em"><i>popclient</i>
always writes the retrieved messages using Unix mail folder
format. This allows <i>popclient</i> to be used in
conjunction with common mail readers like <i>mail</i> and
<i>elm.</i> The retrieved messages are normally appended to
your default system mailbox on the local disk, using the
local Mail Delivery Agent (MDA), usually /bin/mail(1), so
that when you invoke your mail reader it can manipulate the
retrieved messages like any other mail you receive on the
client machine.</p>
<p style="margin-left:11%; margin-top: 1em">Using the
<b>−o</b> option, you can specify a different mail
folder to which the retrieved messages will be appended. If
you prefer, for example, to have your POP mail from a
machine called ’mailgrunt’ stored in the
<i>mbox</i> file in your home directory, you would start
<i>popclient</i> as follows:</p>
<p style="margin-left:22%; margin-top: 1em">popclient
−o $HOME/mbox mailgrunt</p>
<p style="margin-left:11%; margin-top: 1em">Note that the
folder specified with <b>−o</b> is not locked or
otherwise protected from other processes writing to it while
popclient is writing to it.</p>
<p style="margin-left:11%; margin-top: 1em"><i>popclient</i>
can be used in a shell pipeline by using the <b>−c</b>
option. In this mode, <i>popclient</i> writes the retrieved
messages to stdout, instead of a mail folder. This would
allow you, for instance, to pass the incoming mail through a
filter that discards mail marked as ’Precedence:
junk’. Suppose you’ve written an AWK script
called ’dumpjunk.awk’ to implement a junk mail
filter. The appropriate syntax to retrieve your mail from
’mailgrunt’, pass it through the filter, and
write it to a folder called ’realmail’ in your
home directory would be:</p>
<p style="margin-left:22%; margin-top: 1em">popclient -c
mailgrunt | awk -f dumpjunk.awk > $HOME/realmail</p>
<p style="margin-left:11%; margin-top: 1em">The
progress/status messages written to stderr when the
<b>−s</b> option has not been specified, do not
interfere with the message stream, which is written to
stdout. You may even use <b>−v</b> and <b>−c</b>
together without corrupting the message stream. It is a good
idea to use the <b>−k</b> option when using
<b>−c</b> to insure that your messages will not be
lost if part of the shell pipeline does not function
incorrectly. The safest bet would be something like:</p>
<p style="margin-left:22%; margin-top: 1em">popclient -k -c
mailgrunt | myfilter > $HOME/filtered.mail</p>
<p style="margin-left:11%; margin-top: 1em">followed by</p>
<p style="margin-left:22%; margin-top: 1em">popclient -c
mailgrunt > /dev/null</p>
<p style="margin-left:11%; margin-top: 1em">when
you’re sure the messages were correctly processed by
’myfilter’.</p>
<a name="EXIT CODES"></a>
<h2>EXIT CODES</h2>
<p style="margin-left:11%; margin-top: 1em">To facilitate
the use of <i>popclient</i> in shell scripts and the like,
an exit code is returned to give an indication of what
occured during a given POP connection. The exit code can be
tested by the script and appropriate action taken.</p>
<p style="margin-left:11%; margin-top: 1em">A simple
example follows. This Bourne shell script executes
<i>popclient</i> and, if some messages were successfully
retrieved from a mailserver retrieved from the command line,
it starts the <i>mail</i> utility to read those messages.
Otherwise, it prints a brief message, and exits.
#!/bin/sh</p>
<p style="margin-left:11%; margin-top: 1em">if popclient $1
then <br>
mail else <br>
echo "No mail to read." fi</p>
<p style="margin-left:11%; margin-top: 1em">The exit codes
returned by <i>popclient</i> are as follows:</p>
<table width="100%" border=0 rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">0</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">One or more
messages were successfully retrieved.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">1</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">There was no mail
awaiting retrieval.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">2</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">An error was
encountered when attempting to open a socket for the POP
connection. If you don’t know what a socket is,
don’t worry about it -- just treat this as an
’unrecoverable error’.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">3</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">The user
authentication step failed. This usually means that a bad
user-id or password was specified.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">4</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Some sort of
protocol error was detected. POP is not especially forgiving
when it comes to unexpected responses, commands, etc -- the
protocol invariably calls for terminating the connection
under such error conditions.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">5</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">There was a syntax
error in the arguments to <i>popclient.</i></p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">6</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Some kind of I/O
woes occurred when writing to the local folder.</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">7</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">There was an error
condition reported by the server (POP3 only).</p></td>
<tr valign="top" align="left">
<td width="11%"></td>
<td width="1%">
<p style="margin-top: 1em" valign="top">9</p></td>
<td width="10%"></td>
<td width="78%">
<p style="margin-top: 1em" valign="top">Something totally
undefined occured. This is usually caused by a bug within
<i>popclient.</i> Do let me know if this happens.</p></td>
</table>
<a name="AUTHOR"></a>
<h2>AUTHOR</h2>
<p style="margin-left:11%; margin-top: 1em"><i>popclient</i>
was written by Carl Harris at Virginia Polytechnic Institute
and State University (a.k.a. Virginia Tech).</p>
<a name="BUGS"></a>
<h2>BUGS</h2>
<p style="margin-left:11%; margin-top: 1em">There are none!
Well, maybe one or two. Send comments, bug reports, gripes,
and the like to ceharris@vt.edu.</p>
<a name="SEE ALSO"></a>
<h2>SEE ALSO</h2>
<p style="margin-left:11%; margin-top: 1em">mail(1),
binmail(1), sendmail(8), popd(8), RFC 937, RFC 1225.</p>
<hr>
</body>
</html>