Commit 01f05d0c authored by Daniel Stenberg's avatar Daniel Stenberg
Browse files

return code cleanup: build, init and run-time errors 

Stop the abuse of CURLE_FAILED_INIT as return code for things not being
init related by introducing two new return codes:

CURLE_NOT_BUILT_IN and CURLE_UNKNOWN_OPTION

CURLE_NOT_BUILT_IN replaces return code 4 that has been obsoleted for
several years. It is used for returning error when something is
attempted to be used but the feature/option was not enabled or
explictitly disabled at build-time. Getting this error mostly means that
libcurl needs to be rebuilt.

CURLE_FAILED_INIT is now saved and used strictly for init
failures. Getting this problem means something went seriously wrong,
like a resource shortage or similar.

CURLE_UNKNOWN_OPTION is the option formerly known as
CURLE_UNKNOWN_TELNET_OPTION (and the old name is still present,
separately defined to be removed in a very distant future). This error
code is meant to be used to return when an option is given to libcurl
that isn't known. This problem would mostly indicate a problem in the
program that uses libcurl.
parent 8321a367

docs/libcurl/libcurl-errors.3

+13 −5
Original line number Diff line number Diff line
@@ -5,7 +5,7 @@ 
.\" *                            | (__| |_| |  _ <| |___

.\" *                             \___|\___/|_| \_\_____|

.\" *

.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.

.\" *

.\" * This software is licensed as described in the file COPYING, which

.\" * you should have received as part of this distribution. The terms
@@ -44,9 +44,15 @@ can be a misspelled protocol string or just a protocol libcurl has no code 
for.

.IP "CURLE_FAILED_INIT (2)"

Very early initialization code failed. This is likely to be an internal error

or problem.

or problem, or a resource problem where something fundamental couldn't get

done at init time.

.IP "CURLE_URL_MALFORMAT (3)"

The URL was not properly formatted.

.IP "CURLE_NOT_BUILT_IN (4)"

A requested feature, protocol or option was not found built-in in this libcurl

due to a build-time decision. This means that a feature or option was not

enabled or explicitly disabled when libcurl was built and in order to get it

to function you have to get a rebuilt libcurl.

.IP "CURLE_COULDNT_RESOLVE_PROXY (5)"

Couldn't resolve proxy. The given proxy host could not be resolved.

.IP "CURLE_COULDNT_RESOLVE_HOST (6)"
@@ -145,9 +151,11 @@ CURLOPT_INTERFACE. 
.IP "CURLE_TOO_MANY_REDIRECTS (47)"

Too many redirects. When following redirects, libcurl hit the maximum amount.

Set your limit with CURLOPT_MAXREDIRS.

.IP "CURLE_UNKNOWN_TELNET_OPTION (48)"

An option set with CURLOPT_TELNETOPTIONS was not recognized/known. Refer to

the appropriate documentation.

.IP "CURLE_UNKNOWN_OPTION (48)"

An option passed to libcurl is not recognized/known. Refer to the appropriate

documentation. This is most likely a problem in the program that uses

libcurl. The error buffer might contain more specific information about which

exact option it concerns.

.IP "CURLE_TELNET_OPTION_SYNTAX (49)"

A telnet option string was Illegally formatted.

.IP "CURLE_PEER_FAILED_VERIFICATION (51)"

docs/libcurl/symbols-in-versions

+2 −0
Original line number Diff line number Diff line
@@ -82,6 +82,7 @@ CURLE_LDAP_SEARCH_FAILED 7.1 
CURLE_LIBRARY_NOT_FOUND         7.1           7.17.0

CURLE_LOGIN_DENIED              7.13.1

CURLE_MALFORMAT_USER            7.1           7.17.0

CURLE_NOT_BUILT_IN              7.21.5

CURLE_OK                        7.1

CURLE_OPERATION_TIMEDOUT        7.10.2

CURLE_OPERATION_TIMEOUTED       7.1           7.17.0
@@ -123,6 +124,7 @@ CURLE_TFTP_NOTFOUND 7.15.0 
CURLE_TFTP_PERM                 7.15.0

CURLE_TFTP_UNKNOWNID            7.15.0

CURLE_TOO_MANY_REDIRECTS        7.5

CURLE_UNKNOWN_OPTION            7.21.5

CURLE_UNKNOWN_TELNET_OPTION     7.7

CURLE_UNSUPPORTED_PROTOCOL      7.1

CURLE_UPLOAD_FAILED             7.16.3

include/curl/curl.h

+7 −3
Original line number Diff line number Diff line
@@ -7,7 +7,7 @@ 
 *                            | (__| |_| |  _ <| |___

 *                             \___|\___/|_| \_\_____|

 *

 * Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al.

 * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.

 *

 * This software is licensed as described in the file COPYING, which

 * you should have received as part of this distribution. The terms
@@ -401,7 +401,8 @@ typedef enum { 
  CURLE_UNSUPPORTED_PROTOCOL,    /* 1 */

  CURLE_FAILED_INIT,             /* 2 */

  CURLE_URL_MALFORMAT,           /* 3 */

  CURLE_OBSOLETE4,               /* 4 - NOT USED */

  CURLE_NOT_BUILT_IN,            /* 4 - [was obsoleted in August 2007 for

                                    7.17.0, reused in April 2011 for 7.21.5] */

  CURLE_COULDNT_RESOLVE_PROXY,   /* 5 */

  CURLE_COULDNT_RESOLVE_HOST,    /* 6 */

  CURLE_COULDNT_CONNECT,         /* 7 */
@@ -451,7 +452,7 @@ typedef enum { 
  CURLE_INTERFACE_FAILED,        /* 45 - CURLOPT_INTERFACE failed */

  CURLE_OBSOLETE46,              /* 46 - NOT USED */

  CURLE_TOO_MANY_REDIRECTS ,     /* 47 - catch endless re-direct loops */

  CURLE_UNKNOWN_TELNET_OPTION,   /* 48 - User specified an unknown option */

  CURLE_UNKNOWN_OPTION,          /* 48 - User specified an unknown option */

  CURLE_TELNET_OPTION_SYNTAX ,   /* 49 - Malformed telnet option */

  CURLE_OBSOLETE50,              /* 50 - NOT USED */

  CURLE_PEER_FAILED_VERIFICATION, /* 51 - peer's certificate or fingerprint
@@ -518,6 +519,9 @@ typedef enum { 


/* Backwards compatibility with older names */



/* The following were added in 7.21.5, April 2011 */

#define CURLE_UNKNOWN_TELNET_OPTION CURLE_UNKNOWN_OPTION



/* The following were added in 7.17.1 */

/* These are scheduled to disappear by 2009 */

#define CURLE_SSL_PEER_CERTIFICATE CURLE_PEER_FAILED_VERIFICATION

lib/axtls.h

+2 −2
Original line number Diff line number Diff line
@@ -51,8 +51,8 @@ int Curl_axtls_check_cxn(struct connectdata *conn); 
#define curlssl_close_all Curl_axtls_close_all

#define curlssl_close Curl_axtls_close

#define curlssl_shutdown(x,y) Curl_axtls_shutdown(x,y)

#define curlssl_set_engine(x,y) (x=x, y=y, CURLE_FAILED_INIT)

#define curlssl_set_engine_default(x) (x=x, CURLE_FAILED_INIT)

#define curlssl_set_engine(x,y) (x=x, y=y, CURLE_NOT_BUILT_IN)

#define curlssl_set_engine_default(x) (x=x, CURLE_NOT_BUILT_IN)

#define curlssl_engines_list(x) (x=x, (struct curl_slist *)NULL)

#define curlssl_version Curl_axtls_version

#define curlssl_check_cxn(x) Curl_axtls_check_cxn(x)

lib/cyassl.h

+3 −3
Original line number Diff line number Diff line
@@ -52,8 +52,8 @@ CURLcode Curl_cyassl_connect_nonblocking(struct connectdata *conn, 
#define curlssl_close_all Curl_cyassl_close_all

#define curlssl_close Curl_cyassl_close

#define curlssl_shutdown(x,y) Curl_cyassl_shutdown(x,y)

#define curlssl_set_engine(x,y) (x=x, y=y, CURLE_FAILED_INIT)

#define curlssl_set_engine_default(x) (x=x, CURLE_FAILED_INIT)

#define curlssl_set_engine(x,y) (x=x, y=y, CURLE_NOT_BUILT_IN)

#define curlssl_set_engine_default(x) (x=x, CURLE_NOT_BUILT_IN)

#define curlssl_engines_list(x) (x=x, (struct curl_slist *)NULL)

#define curlssl_version Curl_cyassl_version

#define curlssl_check_cxn(x) (x=x, -1)