cURL / Mailing Lists / curl-library / Single Mail


RE: [PATCH] POP3: Expanded the supported commands

From: Steve Holme <>
Date: Sun, 11 Dec 2011 13:54:32 +0000

Hi Dan,

> It sounds from the description above that this patch uses -X not to
> one command with another as sent over the wire, but to actually change
> curl's behaviour by changing the type of transfer performed. It might turn
> out that this approach is the right one for POP-3, but I think that needs
> be debated some more. Such an approach could make it impossible to use
> -X (in the same way as FTP and HTTP) as a future-proof way to extend the
> behaviour of POP-3 in the face of arbitrary future extensions of the
> l (since only those five commands above are supported and no more).

Yep that's exactly what it does ;-)

> It turns out that all those five new commands (and probably most others)
> follow one of two patterns: the command returns with only a response
> code, or it returns with a response code and a multiline response.

All POP3 commands either return +OK or -ERR. Depending on the command the
response will either be nothing else, a single line of information or
multiline of data. If -ERR is returned that typically includes a line of
information and an error code at the end.

A more or less full list of commands and return type is as follows:

STLS +OK information
USER [username] +OK
PASS [password] +OK information
CAPA +OK multiline
STAT +OK information
LIST +OK information multiline
LIST [message id] +OK information
UIDL +OK information multiline
UIDL [message id] +OK information
TOP [message id] +OK multiline
RETR [message id] +OK multiline
DELE [message id] +OK

> That regularity tells me that it should be possible to use -X in the same
> way for POP-3 as FTP and HTTP, that is, to send arbitrary commands by
> replacing only the command and not the behaviour without having to
> change the POP-3 state machine.

You could group the commands together as follows:

Information / Information and Multiline (Listing type commands)

STAT, LIST and UIDL (Although STAT is information only)

Multiline (Retrieval type commands)


No Information (Instruction type commands)


I've not included STLS, USER or PASS in that list as these are behind the
scenes connection based commands.

I've also not included CAPA (which returns the server's capabilities) in the
list either as I don't know how widely used the command is and haven't
included support for it yet either.

> Since a normal message retrieval (RETR) returns a response code (*)
> and a multiline response, any other POP-3 command that returns
> something similar should be able to be replaced and work correctly. So,
> implementing TOP (and all other similar POP-3 commands, like UIDL)
> should work by using a normal message URL (which normally sends an
> RETR) and -X TOP to send TOP instead (** there's an important gotcha
> discussed later). Instead of returning the full message body, TOP would
> return just the top few bytes of the message in place of the body from
> the application's point of view.

You can view UIDL as an extended version of LIST (LIST returns the session's
message id and the message size whilst UIDL returns the session's message id
and the server's unique id - client applications can then store this unique
id so the next time they connect they can perform a UIDL to see which
messages they need to retrieve) and TOP is an extended version of RETR (With
the introduction of file attachments, emails became quite long, so TOP was
introduced to allow client applications to get just the headers of a

Neither of these two commands were present in the original POP3
specification but as it was only two commands I didn't see much point - I
could do away with the UIDL state and response function (and use the list
version instead) and likewise with the TOP and RETR commands just use one
state machine state and response function. You could then use -X in these
circumstance (which I guess would then be in keeping with the command under
HTTP) however, how do we support commands like NOOP, DELE and RSET?

> Likewise, implementing NOOP, STAT, DELE and RSET (and all other
> similar POP-3 commands) could be done by using -X STAT (or whatever)
> instead of a normal command that returns just a response code and not a
> multiline response (*** of which there is unfortunately currently none
> supported in curl; see below).

As I see it, we would need three types of URLs then:

pop3:// - which performs a listing / informational command.
LIST by default, UIDL and STAT when using -X and possible CAPA in the
pop3:// - which performs a message retrieval
command. RETR by default and TOP when using -X but LIST when using -l and
UIDL when using -l -X UIDL.
pop3:// - which performs an instruction. I'm not
sure which by default and the others when using -X. We would also need to
define xxx in the URL is as well ;-)
> I haven't really looked at the patch details; when I saw the command-
> specific changes to the state machine, I just got the feeling that there
> must be a more generic way to support these commands.

Unfortunately, I'm a little pushed for time at the moment and I needed to
get something up and running for the other projects I'm working on, so my
initial version of this was using the URL syntax that we discussed and now I
have reworked that to something, as you have seen, that totally relies on
the -X... but what I think has come to light here is that there may be a
third way which uses a combination of the two - is that correct?

This third way also seems a little complicated from an application
programmer's point of view (although I agree it is probably more in keeping
with curl's usage of -X).

However, I can't make the decision as to the best way to go as I've only
been hanging out here for the last 6 months ;-)

Kind Regards


List admin:
Received on 2011-12-11