On Mon, 27 Aug 2007, Dan Fandrich wrote:

> The libcurl API now defines 81 different error codes from the curl_easy_*
> series of functions. That's a lot of error codes! It turns out that there
> are many duplicate and unused error codes in the bunch. Most of the
> duplicates are there because the original codes had a specific protocol in
> the name and a similar error needed to be returned by a new protocol.

Yes, originally I thought that was a good idea but I've reconsidered my
opinion since and I no longer believe that! I makes much more sense to try to
have the same "file not found" (as an example) returned no matter what
protocol that were used, as applications will be much easier to write with
multiple protocol support then.

> I propose changing the codes in two steps. The first step could be done
> right now and will preserve 100% backward compatibility (essentially). That
> would consist of renaming some errors to take the protocols out of the names
> and make them suitable for more general use. Macros to define the old names
> in terms of the new ones would be added to preserve compatibility, but they
> would be added in a CURL_NO_OLDIES section

Yeah, and we could do this already before the next release.

> Some time in the future (or maybe never) the old names would go away.
> Unused error codes would be removed as well at this stage (without leaving a
> "hole" in the error code list, of course).

We should just make sure to make a note in the changelog when we start seeing
them as obsolete, so that we can have a decent age counter on them. I mean,
two or three years in the future it'll be good to mention that when the
argument comes up...

> At the next SONAME bump, when compatibility guarantees are no longer valid,
> the libcurl code would be changed to remove references to the duplicate
> errors and replace them with the generic error codes. This is a minor
> compatibility burp, and many programs would still continue to operate just
> fine expecting the old error codes even if they weren't recompiled (which
> they are forced to do by the SONAME change, except when distros (like
> Debian) just symlink the old name to the new).

I know this may come of sound odd, but they deserve a slap in the face for
blatantly ignoring our soname bump anyway.

A small recap for the casual readers: the Debian guys clearly know better than
us about when an soname bump is required for libcurl and they deemed our
latest one not necessary so they simply install the latest libcurl as soname 3
and symlink 4 to 3, thus breaking older apps relying on the previous ABI...

> CURLE_OPERATION_TIMEOUTED => CURLE_OPERATION_TIMED_OUT
> CURLE_FTP_QUOTE_ERROR => CURLE_QUOTE_ERROR
> CURLE_FTP_ACCESS_DENIED => CURLE_REMOTE_ACCESS_DENIED
> CURLE_TFTP_DISKFULL => CURLE_REMOTE_DISK_FULL
> CURLE_TFTP_EXISTS => CURLE_FILE_EXISTS
> CURLE_FUNCTION_NOT_FOUND => CURLE_FAILED_INIT
> CURLE_HTTP_RANGE_ERROR => CURLE_RANGE_ERROR

I like them all! Possibly the CURLE_FILE_EXISTS should be called
CURLE_REMOTE_FILE_EXISTS to fit into the new set of REMOTE error codes.

> These are the codes I would like to see removed, as they are unused.
> Removal would consist of replacing the code with a name like
> CURLE_OBSOLETE50 and creating macros with these old names to the new ones.
> (A few of these look like they ought to be supported in the code--maybe they
> were removed accidentally?)

I think some of them are usable and could be used right now, but over time
when source codes have changed and unified etc some error codes just have not
been easily used anymore.

> At the next SONAME bump, I'd like to see the following options combined,
> i.e. references to the first name replaced by the second.
>
> CURLE_FILE_COULDNT_READ_FILE => CURLE_REMOTE_FILE_NOT_FOUND
> CURLE_TFTP_NOTFOUND => CURLE_REMOTE_FILE_NOT_FOUND
> CURLE_FTP_COULDNT_RETR_FILE => CURLE_REMOTE_FILE_NOT_FOUND
> CURLE_LDAP_INVALID_URL => CURLE_URL_MALFORMAT
> CURLE_TFTP_PERM => CURLE_REMOTE_ACCESS_DENIED
> CURLE_TFTP_NOSUCHUSER => CURLE_TFTP_ILLEGAL
> CURLE_FTP_COULDNT_USE_REST => CURLE_RANGE_ERROR

A full ack for this too.

> Similarly, there are a few curl_easy_setopt options I'd like to see renamed
> for similar reasons. This could be done now, with backward-compatible names
> added:
>
> CURLOPT_SSLKEYPASSWD => CURLOPT_KEYPASSWD
> *CURLOPT_FTPAPPEND => CURLOPT_APPEND
> *CURLOPT_FTPLISTONLY => CURLOPT_DIRLISTONLY
>
> * These last two options aren't currently used by protocols other than FTP,
> but it's conceivable that they could be in the future.

Yes, it makes sense to allow options to be used for multiple protocols when
they have (basically) the same meaning.

As you may have seen, there's a "NEXT soname bump" chapter in the docs/TODO
file in which we can add soname bump changes under so that we won't forget
them.

I'm also for adding code with suitable #ifdefs for the soname bump so that we
can test-build the changes already before the actual change. Preferably we'll
make it so that we can set a single define to test all soname bump changes at
once.

-- 
  Commercial curl and libcurl Technical Support: http://haxx.se/curl.html