Permalink
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.
  • Loading branch information...
1 parent 8321a36 commit 01f05d0c758795e5bb02c6245fc73b8458eb397a @bagder bagder committed Apr 5, 2011
Showing with 58 additions and 41 deletions.
  1. +13 −5 docs/libcurl/libcurl-errors.3
  2. +2 −0 docs/libcurl/symbols-in-versions
  3. +7 −3 include/curl/curl.h
  4. +2 −2 lib/axtls.h
  5. +3 −3 lib/cyassl.h
  6. +1 −1 lib/ftp.c
  7. +3 −3 lib/gtls.h
  8. +1 −1 lib/http_proxy.h
  9. +3 −3 lib/nssg.h
  10. +2 −2 lib/polarssl.h
  11. +3 −3 lib/qssl.h
  12. +2 −2 lib/socks.h
  13. +5 −5 lib/sslgen.h
  14. +6 −3 lib/strerror.c
  15. +5 −5 lib/url.c
View
18 docs/libcurl/libcurl-errors.3
@@ -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)"
View
2 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
View
10 include/curl/curl.h
@@ -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
View
4 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)
View
6 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)
View
2 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);
View
6 lib/gtls.h
@@ -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
@@ -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)
View
2 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
View
6 lib/nssg.h
@@ -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
@@ -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)
View
4 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)
View
6 lib/qssl.h
@@ -7,7 +7,7 @@
* | (__| |_| | _ <| |___
* \___|\___/|_| \_\_____|
*
- * Copyright (C) 1998 - 2008, 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
@@ -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)
View
4 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
View
10 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 */
View
9 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:
View
10 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;
}

0 comments on commit 01f05d0

Please sign in to comment.