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. For example, the error codes

  CURLE_FILE_COULDNT_READ_FILE
  CURLE_TFTP_NOTFOUND
  CURLE_FTP_COULDNT_RETR_FILE
  CURLE_REMOTE_FILE_NOT_FOUND

all mean the same thing--that a remote resource was not found. Since there
is never a need to distinguish between them (only one of the codes could
possibly be returned for any handle handle, depending on the URL),
they should all be replaced by a single code. But that's undesirable
for backward compatibility reasons.

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
so people can easily see if their programs are relying on the old names and
fix them. 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).

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).

These are the codes I would want to see renamed immediately:

  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

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?)

  CURLE_BAD_PASSWORD_ENTERED
  CURLE_BAD_CALLING_ORDER
  CURLE_FTP_USER_PASSWORD_INCORRECT
  CURLE_FTP_CANT_RECONNECT
  CURLE_FTP_COULDNT_GET_SIZE
  CURLE_FTP_COULDNT_SET_ASCII
  CURLE_FTP_WEIRD_USER_REPLY
  CURLE_FTP_WRITE_ERROR
  CURLE_LIBRARY_NOT_FOUND
  CURLE_MALFORMAT_USER
  CURLE_SHARE_IN_USE
  CURLE_URL_MALFORMAT_USER

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

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.

What is the consensus of the list on this proposal?

>>> Dan

-- 
http://www.MoveAnnouncer.com              The web change of address service
          Let webmasters know that your web site has moved