From 01f05d0c758795e5bb02c6245fc73b8458eb397a Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 5 Apr 2011 15:14:02 +0200 Subject: 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. --- docs/libcurl/libcurl-errors.3 | 18 +++++++++++++----- docs/libcurl/symbols-in-versions | 2 ++ include/curl/curl.h | 10 +++++++--- lib/axtls.h | 4 ++-- lib/cyassl.h | 6 +++--- lib/ftp.c | 2 +- lib/gtls.h | 6 +++--- lib/http_proxy.h | 2 +- lib/nssg.h | 6 +++--- lib/polarssl.h | 4 ++-- lib/qssl.h | 6 +++--- lib/socks.h | 4 ++-- lib/sslgen.h | 10 +++++----- lib/strerror.c | 9 ++++++--- lib/url.c | 10 +++++----- 15 files changed, 58 insertions(+), 41 deletions(-) diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3 index c3c854e90..beabf98f0 100644 --- a/docs/libcurl/libcurl-errors.3 +++ b/docs/libcurl/libcurl-errors.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. +.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, , 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)" diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index fca917a97..aa86b913a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -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 diff --git a/include/curl/curl.h b/include/curl/curl.h index 73713dd07..2bd9cd042 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -7,7 +7,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. + * Copyright (C) 1998 - 2011, Daniel Stenberg, , 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 diff --git a/lib/axtls.h b/lib/axtls.h index f1e94b65c..967f90930 100644 --- a/lib/axtls.h +++ b/lib/axtls.h @@ -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) diff --git a/lib/cyassl.h b/lib/cyassl.h index 6dbf70f4d..a21592a28 100644 --- a/lib/cyassl.h +++ b/lib/cyassl.h @@ -51,9 +51,9 @@ CURLcode Curl_cyassl_connect_nonblocking(struct connectdata *conn, #define curlssl_session_free(x) Curl_cyassl_session_free(x) #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_shutdown(x,y) Curl_cyassl_shutdown(x,y) +#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) diff --git a/lib/ftp.c b/lib/ftp.c index 6a6a6de69..154a03607 100644 --- a/lib/ftp.c +++ b/lib/ftp.c @@ -2456,7 +2456,7 @@ static CURLcode ftp_statemach_act(struct connectdata *conn) default: failf(data, "unsupported parameter to CURLOPT_FTPSSLAUTH: %d", (int)data->set.ftpsslauth); - return CURLE_FAILED_INIT; /* we don't know what to do */ + return CURLE_UNKNOWN_OPTION; /* we don't know what to do */ } PPSENDF(&ftpc->pp, "AUTH %s", ftpauth[ftpc->count1]); state(conn, FTP_AUTH); diff --git a/lib/gtls.h b/lib/gtls.h index 51e0af1f5..6275b49a3 100644 --- a/lib/gtls.h +++ b/lib/gtls.h @@ -7,7 +7,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. + * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms @@ -52,8 +52,8 @@ int Curl_gtls_seed(struct SessionHandle *data); #define curlssl_close_all Curl_gtls_close_all #define curlssl_close Curl_gtls_close #define curlssl_shutdown(x,y) Curl_gtls_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_gtls_version #define curlssl_check_cxn(x) (x=x, -1) diff --git a/lib/http_proxy.h b/lib/http_proxy.h index da08fa50a..271b98a6e 100644 --- a/lib/http_proxy.h +++ b/lib/http_proxy.h @@ -29,5 +29,5 @@ CURLcode Curl_proxyCONNECT(struct connectdata *conn, #define PROXY_TIMEOUT (3600*1000) #else -#define Curl_proxyCONNECT(x,y,x,w) CURLE_FAILED_INIT +#define Curl_proxyCONNECT(x,y,x,w) CURLE_NOT_BUILT_IN #endif diff --git a/lib/nssg.h b/lib/nssg.h index f9cc46ae2..438d5a636 100644 --- a/lib/nssg.h +++ b/lib/nssg.h @@ -7,7 +7,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) 1998 - 2010, Daniel Stenberg, , et al. + * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms @@ -60,8 +60,8 @@ CURLcode Curl_nss_force_init(struct SessionHandle *data); #define curlssl_close Curl_nss_close /* NSS has no shutdown function provided and thus always fail */ #define curlssl_shutdown(x,y) (x=x, y=y, 1) -#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_nss_version #define curlssl_check_cxn(x) Curl_nss_check_cxn(x) diff --git a/lib/polarssl.h b/lib/polarssl.h index 964af1728..9e983aac9 100644 --- a/lib/polarssl.h +++ b/lib/polarssl.h @@ -46,8 +46,8 @@ int Curl_polarssl_shutdown(struct connectdata *conn, int sockindex); #define curlssl_close_all Curl_polarssl_close_all #define curlssl_close Curl_polarssl_close #define curlssl_shutdown(x,y) 0 -#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_polarssl_version #define curlssl_check_cxn(x) (x=x, -1) diff --git a/lib/qssl.h b/lib/qssl.h index 45190e623..bd195ff7b 100644 --- a/lib/qssl.h +++ b/lib/qssl.h @@ -7,7 +7,7 @@ * | (__| |_| | _ <| |___ * \___|\___/|_| \_\_____| * - * Copyright (C) 1998 - 2008, Daniel Stenberg, , et al. + * Copyright (C) 1998 - 2011, Daniel Stenberg, , et al. * * This software is licensed as described in the file COPYING, which * you should have received as part of this distribution. The terms @@ -49,8 +49,8 @@ int Curl_qsossl_check_cxn(struct connectdata * cxn); #define curlssl_close_all Curl_qsossl_close_all #define curlssl_close Curl_qsossl_close #define curlssl_shutdown(x,y) Curl_qsossl_shutdown(x,y) -#define curlssl_set_engine(x,y) CURLE_FAILED_INIT -#define curlssl_set_engine_default(x) CURLE_FAILED_INIT +#define curlssl_set_engine(x,y) CURLE_NOT_BUILT_IN +#define curlssl_set_engine_default(x) CURLE_NOT_BUILT_IN #define curlssl_engines_list(x) NULL #define curlssl_version Curl_qsossl_version #define curlssl_check_cxn(x) Curl_qsossl_check_cxn(x) diff --git a/lib/socks.h b/lib/socks.h index 1c686d181..42b8080b0 100644 --- a/lib/socks.h +++ b/lib/socks.h @@ -25,8 +25,8 @@ #include "setup.h" #ifdef CURL_DISABLE_PROXY -#define Curl_SOCKS4(a,b,c,d,e,f) CURLE_FAILED_INIT -#define Curl_SOCKS5(a,b,c,d,e,f) CURLE_FAILED_INIT +#define Curl_SOCKS4(a,b,c,d,e,f) CURLE_NOT_BUILT_IN +#define Curl_SOCKS5(a,b,c,d,e,f) CURLE_NOT_BUILT_IN #else /* * Helper read-from-socket functions. Does the same as Curl_read() but it diff --git a/lib/sslgen.h b/lib/sslgen.h index af582e06f..b0a0fab12 100644 --- a/lib/sslgen.h +++ b/lib/sslgen.h @@ -72,12 +72,12 @@ void Curl_ssl_delsessionid(struct connectdata *conn, void *ssl_sessionid); /* When SSL support is not present, just define away these function calls */ #define Curl_ssl_init() 1 #define Curl_ssl_cleanup() do { } while (0) -#define Curl_ssl_connect(x,y) CURLE_FAILED_INIT +#define Curl_ssl_connect(x,y) CURLE_NOT_BUILT_IN #define Curl_ssl_close_all(x) #define Curl_ssl_close(x,y) -#define Curl_ssl_shutdown(x,y) CURLE_FAILED_INIT -#define Curl_ssl_set_engine(x,y) CURLE_FAILED_INIT -#define Curl_ssl_set_engine_default(x) CURLE_FAILED_INIT +#define Curl_ssl_shutdown(x,y) CURLE_NOT_BUILT_IN +#define Curl_ssl_set_engine(x,y) CURLE_NOT_BUILT_IN +#define Curl_ssl_set_engine_default(x) CURLE_NOT_BUILT_IN #define Curl_ssl_engines_list(x) NULL #define Curl_ssl_send(a,b,c,d,e) -1 #define Curl_ssl_recv(a,b,c,d,e) -1 @@ -86,7 +86,7 @@ void Curl_ssl_delsessionid(struct connectdata *conn, void *ssl_sessionid); #define Curl_ssl_data_pending(x,y) 0 #define Curl_ssl_check_cxn(x) 0 #define Curl_ssl_free_certinfo(x) -#define Curl_ssl_connect_nonblocking(x,y,z) CURLE_FAILED_INIT +#define Curl_ssl_connect_nonblocking(x,y,z) CURLE_NOT_BUILT_IN #endif #endif /* USE_SSL */ diff --git a/lib/strerror.c b/lib/strerror.c index a88cdc4eb..8144f78f0 100644 --- a/lib/strerror.c +++ b/lib/strerror.c @@ -65,6 +65,10 @@ curl_easy_strerror(CURLcode error) case CURLE_URL_MALFORMAT: return "URL using bad/illegal format or missing URL"; + case CURLE_NOT_BUILT_IN: + return "A requested feature, protocol or option was not found built-in in" + " this libcurl due to a build-time decision."; + case CURLE_COULDNT_RESOLVE_PROXY: return "Couldn't resolve proxy name"; @@ -167,8 +171,8 @@ curl_easy_strerror(CURLcode error) case CURLE_TOO_MANY_REDIRECTS : return "Number of redirects hit maximum amount"; - case CURLE_UNKNOWN_TELNET_OPTION: - return "User specified an unknown telnet option"; + case CURLE_UNKNOWN_OPTION: + return "An unknown option was passed in to libcurl"; case CURLE_TELNET_OPTION_SYNTAX : return "Malformed telnet option"; @@ -282,7 +286,6 @@ curl_easy_strerror(CURLcode error) return "Chunk callback failed"; /* error codes not used by current libcurl */ - case CURLE_OBSOLETE4: case CURLE_OBSOLETE10: case CURLE_OBSOLETE12: case CURLE_OBSOLETE16: diff --git a/lib/url.c b/lib/url.c index 5ece35ed2..c7fcdfe96 100644 --- a/lib/url.c +++ b/lib/url.c @@ -988,7 +988,7 @@ CURLcode Curl_setopt(struct SessionHandle *data, CURLoption option, break; default: /* reserve other values for future use */ - result = CURLE_FAILED_INIT; + result = CURLE_UNKNOWN_OPTION; break; } break; @@ -1428,7 +1428,7 @@ CURLcode Curl_setopt(struct SessionHandle *data, CURLoption option, auth &= ~CURLAUTH_GSSNEGOTIATE; /* no GSS-Negotiate without GSSAPI or WINDOWS_SSPI */ #endif if(!auth) - return CURLE_FAILED_INIT; /* no supported types left! */ + return CURLE_NOT_BUILT_IN; /* no supported types left! */ data->set.httpauth = auth; } @@ -1488,7 +1488,7 @@ CURLcode Curl_setopt(struct SessionHandle *data, CURLoption option, auth &= ~CURLAUTH_GSSNEGOTIATE; /* no GSS-Negotiate without GSSAPI or WINDOWS_SSPI */ #endif if(!auth) - return CURLE_FAILED_INIT; /* no supported types left! */ + return CURLE_NOT_BUILT_IN; /* no supported types left! */ data->set.proxyauth = auth; } @@ -1528,7 +1528,7 @@ CURLcode Curl_setopt(struct SessionHandle *data, CURLoption option, break; default: /* reserve other values for future use */ - result = CURLE_FAILED_INIT; + result = CURLE_UNKNOWN_OPTION; break; } break; @@ -2518,7 +2518,7 @@ CURLcode Curl_setopt(struct SessionHandle *data, CURLoption option, #endif default: /* unknown tag and its companion, just ignore: */ - result = CURLE_FAILED_INIT; /* correct this */ + result = CURLE_UNKNOWN_OPTION; break; } -- cgit v1.2.3