pop3d(3tcl)

💖 pop3d — the Tcl POP3 Server Package, bestie edition 💖

okay so. you want to run a POP3 server. in Tcl. and you want it to be cute and correct. say less, we got you 🫶 this is the pop3d page from the Tcl POP3 Server Package, and I'm gonna walk you through every single flag like we're texting at 2am.

---

✨ NAME ✨

pop3d — the Tcl POP3 server implementation. that's it, that's the name, it ate 💅

---

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require pop3d ?1.2.0?

::pop3d::new ?serverName?

serverName option ?arg arg ...?

serverName up

serverName down

serverName destroy ?mode?

serverName configure

serverName configure -option

serverName configure -option value...

serverName cget -option

serverName conn list

serverName conn state id

authCmd exists name

authCmd lookup name

storageCmd dele mbox msgList

storageCmd lock mbox

storageCmd unlock mbox

storageCmd size mbox ?msgId?

storageCmd stat mbox

storageCmd get mbox msgId

like, the whole vibe of the package in one code block. iconic.

---

🦋 DESCRIPTION 🦋

::pop3d::new ?serverName?

This command creates a brand new server object, and it comes with a global Tcl command attached to it whose name is serverName. new bestie acquired, no cap.

The command serverName is how you invoke all the various operations on the server. it's got this general form:

serverName option ?arg arg ...?

where option and the args decide the exact behavior of the command. so it's giving "one command, many moods" 💅

A pop3 server can be started on any port the caller has permission for from the operating system — like, the OS has to say yes first, we don't just barge in. The default port is 110, which is the port defined by the standard specified in RFC 1939 (http://www.rfc-editor.org/rfc/rfc1939.txt). After creating, configuring and starting, the server object will listen for and accept connections on that port and handle them according to the POP3 protocol. she's listening 👑

Note: the server provided by this module handles only the basic protocol by itself. For the higher levels of user authentication and handling of the actual mailbox contents, callbacks will be invoked. so you gotta bring your own auth and your own mailbox logic. the server is the stage, you're the performer ✨

The following commands are possible for server objects:

serverName up

After this call the server will listen for connections on its configured port. wake up babe, we're live 🌈

serverName down

After this call the server will stop listening for connections. This does not affect existing connections. they're grandfathered in, they stay, we don't evict them 😌

serverName destroy ?mode?

Destroys the server object. Currently open connections are handled depending on the chosen mode. The provided modes are:

• kill — Destroys the server immediately, and forcefully closes all currently open connections. This is the default mode. it's giving no survivors 💀
• defer — Stops the server from accepting new connections, and will actually destroy it only after the last of the currently open connections for the server is closed. so polite. so patient. 🎀

serverName configure

Returns a list containing all options and their current values, in a format suitable for use by the command array set. The options themselves are described in section Options.

serverName configure -option

Returns the current value of the specified option. This is an alias for the method cget. The options themselves are described in section Options.

serverName configure -option value...

Sets the specified option to the provided value. The options themselves are described in section Options.

serverName cget -option

Returns the current value of the specified option. The options themselves are described in section Options.

serverName conn list

Returns a list containing the ids of all connections currently open. roll call 📋

serverName conn state id

Returns a list suitable for [array set] containing the state of the connection referenced by id. peek at what your connection is going through, respectfully 🫶

---

🎀 OPTIONS 🎀

The following options are available to pop3 server objects. one bullet per option, no skips, we do not gatekeep 💖

• -port port — Defines the port to listen on for new connections. Default is 110. This option is a bit special, lowkey the main character. If port is set to "0" the server, or rather the operating system, will select a free port on its own. When querying -port the id of this chosen port will be returned. Changing the port while the server is up will neither change the returned value, nor will it change on which port the server is listening on. Only after resetting the server via a call to down followed by a call to up will the new port take effect. It is at that time that the value returned when querying -port will change too. so like, she commits when she commits 😭
• -auth command — Defines a command prefix to call whenever the authentication of a user is required. If no such command is specified, the server will reject all users. harsh but honest. The interface which has to be provided by the command prefix is described in section Authentication.
• -storage command — Defines a command prefix to call whenever the handling of mailbox contents is required. If no such command is specified, the server will claim that all mailboxes are empty. The interface which has to be provided by the command prefix is described in section Mailboxes.
• -socket command — Defines a command prefix to call for opening the listening socket. This can be used to make the pop3 server listen on an SSL socket as provided by the tls package, see the command tls::socket. secure her up 🔐

---

💜 AUTHENTICATION 💜

Here we describe the interface which has to be provided by the authentication callback, so that pop3 servers following the interface of this module are able to use it. you're building the bouncer, this is the job description 🫡

authCmd exists name

This method is given a username and has to return a boolean value telling whether or not the specified user exists. yes or no, bestie, no essay answers 💅

authCmd lookup name

This method is given a username and has to return a two-element list containing the password for this user and a storage reference, in this order. order matters!! password first, storage reference second, periodt.

The storage reference is passed unchanged to the storage callback, see sections Options and Mailboxes for either the option defining it and/or the interface to provide, respectively. so she just gets handed off, untouched, no editing, no notes ✨

---

🍓 MAILBOXES 🍓

Here we describe the interface which has to be provided by the storage callback, so that pop3 servers following the interface of this module are able to use it. The mbox argument is the storage reference as returned by the lookup method of the authentication command, see section Authentication. it's the same girl from before, she's back 💖

storageCmd dele mbox msgList

Deletes the messages whose numeric ids are contained in the msgList from the mailbox specified via mbox. bye bye 🦋

storageCmd lock mbox

This method locks the specified mailbox for use by a single connection to the server. This is necessary to prevent havoc if several connections to the same mailbox are open. The complementary method is unlock. The command will return true if the lock could be set successfully or false if not. one at a time, we don't share 🎀

storageCmd unlock mbox

This is the complementary method to lock, it revokes the lock on the specified mailbox. lock off, you're free ✨

storageCmd size mbox ?msgId?

Determines the size of the message specified through its id in msgId, in bytes, and returns this number. The command will return the size of the whole maildrop if no message id was specified. bytes are bytes, no vibes-based estimates 🔥

storageCmd stat mbox

Determines the number of messages in the specified mailbox and returns this number. how many, exactly, no rounding 💅

storageCmd get mbox msgId

Returns a handle for the specified message. This handle is a mime token following the interface described in the documentation of package mime. The pop3 server will use the functionality of the mime token to send the mail to the requestor at the other end of a pop3 connection. handoff complete, the mail is going home 🫶

---

🌈 SECURE MAIL TRANSFER 🌈

The option -socket (see Options) enables users of the package to override how the server opens its listening socket. The envisioned main use is the specification of the tls::socket command, see package tls, to secure the communication. glow up your connection 🔐✨

package require tls
tls::init \
   ...

pop3d::new S -socket tls::socket
...

---

⭐ REFERENCES ⭐

1. RFC 1939 [http://www.rfc-editor.org/rfc/rfc1939.txt]
2. RFC 2449 [http://www.rfc-editor.org/rfc/rfc2449.txt]

the receipts, for the girlies who like receipts 📚

---

💀 BUGS, IDEAS, FEEDBACK 💀

This document, and the package it describes, will undoubtedly contain bugs and other problems. ngl, every doc does. Please report such in the category pop3d of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. we want your thoughts, fr fr 💖

When proposing code changes, please provide unified diffs, i.e the output of diff -u. so we can actually read what changed 🙈

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar. click the left-most button, bestie, that's the one 👑

---

🔥 KEYWORDS 🔥

internet, network, pop3, protocol, rfc 1939, secure, ssl, tls

---

👑 CATEGORY 👑

Networking

---

🎀 COPYRIGHT 🎀

Copyright (c) 2002-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
Copyright (c) 2005 Reinhard Max  <max@suse.de>

---

okay that's the whole page, we made it, no cap 💅 this was tcllib version 1.2.0 of the pop3d(3tcl) page, and the credits up there are the icons who built her — Andreas Kupries and Reinhard Max, we love you, mwah 🫶✨ go start that server bestie 💖