diff --git a/docs/examples/Makefile.am b/docs/examples/Makefile.am index 6759d97f1edb74..614e8f3e2f542d 100644 --- a/docs/examples/Makefile.am +++ b/docs/examples/Makefile.am @@ -34,7 +34,8 @@ EXTRA_DIST = README.md Makefile.example Makefile.inc Makefile.m32 \ # # $(top_srcdir)/include is for libcurl's external include files -AM_CPPFLAGS = -I$(top_srcdir)/include +AM_CPPFLAGS = -I$(top_srcdir)/include \ + -DCURL_DISABLE_DEPRECATION LIBDIR = $(top_builddir)/lib diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3 index 457697ccb14e20..da7752767b479c 100644 --- a/docs/libcurl/curl_easy_setopt.3 +++ b/docs/libcurl/curl_easy_setopt.3 @@ -126,11 +126,14 @@ Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP .IP CURLOPT_SSL_CTX_DATA Data pointer to pass to the SSL context callback. See \fICURLOPT_SSL_CTX_DATA(3)\fP .IP CURLOPT_CONV_TO_NETWORK_FUNCTION -Callback for code base conversion. See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION -Callback for code base conversion. See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP .IP CURLOPT_CONV_FROM_UTF8_FUNCTION -Callback for code base conversion. See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP +\fBOBSOLETE\fP Callback for code base conversion. +See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP .IP CURLOPT_INTERLEAVEFUNCTION Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP .IP CURLOPT_INTERLEAVEDATA diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 index 1c6a921fdc2c93..dd9c8a3e1ef290 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -96,7 +96,7 @@ curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, my_conv_from_ascii_to_ebcdic); .fi .SH AVAILABILITY -Not available since 7.82.0 +Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 index a5479a206f6eaf..501306f18e7a10 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 @@ -94,7 +94,7 @@ curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, my_conv_from_utf8_to_ebcdic); .fi .SH AVAILABILITY -Not available since 7.82.0 +Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 index 036552428e5bd2..0e53d2041769cd 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 @@ -95,7 +95,7 @@ curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, my_conv_from_ebcdic_to_ascii); .fi .SH AVAILABILITY -Not available since 7.82.0 +Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 index cef50c804a1cfc..cf1a2af51f55dc 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 @@ -110,8 +110,9 @@ All curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback); .fi .SH AVAILABILITY -Deprecated in 7.32.0. +Deprecated since 7.32.0. .SH RETURN VALUE Returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), " +.BR CURLOPT_XFERINFOFUNCTION "(3)" diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 0be5fe87fababd..59c66b4e35392a 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -23,6 +23,7 @@ CURL_CHUNK_END_FUNC_OK 7.21.0 CURL_CSELECT_ERR 7.16.3 CURL_CSELECT_IN 7.16.3 CURL_CSELECT_OUT 7.16.3 +CURL_DEPRECATED 7.87.0 CURL_DID_MEMORY_FUNC_TYPEDEFS 7.49.0 CURL_EASY_NONE 7.14.0 - 7.15.4 CURL_EASY_TIMEOUT 7.14.0 - 7.15.4 @@ -61,6 +62,7 @@ CURL_HTTPPOST_PTRBUFFER 7.46.0 CURL_HTTPPOST_PTRCONTENTS 7.46.0 CURL_HTTPPOST_PTRNAME 7.46.0 CURL_HTTPPOST_READFILE 7.46.0 +CURL_IGNORE_DEPRECATION 7.87.0 CURL_IPRESOLVE_V4 7.10.8 CURL_IPRESOLVE_V6 7.10.8 CURL_IPRESOLVE_WHATEVER 7.10.8 @@ -886,6 +888,7 @@ CURLOPT_WS_OPTIONS 7.86.0 CURLOPT_XFERINFODATA 7.32.0 CURLOPT_XFERINFOFUNCTION 7.32.0 CURLOPT_XOAUTH2_BEARER 7.33.0 +CURLOPTDEPRECATED 7.87.0 CURLOPTTYPE_BLOB 7.71.0 CURLOPTTYPE_CBPOINT 7.73.0 CURLOPTTYPE_FUNCTIONPOINT 7.1 diff --git a/include/curl/curl.h b/include/curl/curl.h index 61ca2724dad257..9ae27f87d722b8 100644 --- a/include/curl/curl.h +++ b/include/curl/curl.h @@ -33,6 +33,23 @@ #define CURL_STRICTER #endif +/* Compile-time deprecation macros. */ +#if defined(__GNUC__) && defined(__GNUC_MINOR__) && \ + ((__GNUC__ > 4) || (__GNUC__ == 4 && __GNUC_MINOR__ >= 3)) && \ + !defined(__INTEL_COMPILER) && \ + !defined(CURL_DISABLE_DEPRECATION) && !defined(BUILDING_LIBCURL) +#define CURL_DEPRECATED(version, message) \ + __attribute__((deprecated("since " # version ". " message))) +#define CURL_IGNORE_DEPRECATION(statements) \ + _Pragma("GCC diagnostic push") \ + _Pragma("GCC diagnostic ignored \"-Wdeprecated-declarations\"") \ + statements \ + _Pragma("GCC diagnostic pop") +#else +#define CURL_DEPRECATED(version, message) +#define CURL_IGNORE_DEPRECATION(statements) statements +#endif + #include "curlver.h" /* libcurl version defines */ #include "system.h" /* determine things run-time */ @@ -145,11 +162,11 @@ typedef enum { CURLSSLBACKEND_NSS = 3, CURLSSLBACKEND_OBSOLETE4 = 4, /* Was QSOSSL. */ CURLSSLBACKEND_GSKIT = 5, - CURLSSLBACKEND_POLARSSL = 6, + CURLSSLBACKEND_POLARSSL CURL_DEPRECATED(7.69.0, "") = 6, CURLSSLBACKEND_WOLFSSL = 7, CURLSSLBACKEND_SCHANNEL = 8, CURLSSLBACKEND_SECURETRANSPORT = 9, - CURLSSLBACKEND_AXTLS = 10, /* never used since 7.63.0 */ + CURLSSLBACKEND_AXTLS CURL_DEPRECATED(7.61.0, "") = 10, CURLSSLBACKEND_MBEDTLS = 11, CURLSSLBACKEND_MESALINK = 12, CURLSSLBACKEND_BEARSSL = 13, @@ -1062,6 +1079,7 @@ typedef CURLSTScode (*curl_hstswrite_callback)(CURL *easy, #define CURLOPT(na,t,nu) na = t + nu +#define CURLOPTDEPRECATED(na,t,nu,v,m) na CURL_DEPRECATED(v,m) = t + nu /* CURLOPT aliases that make no run-time difference */ @@ -1175,7 +1193,8 @@ typedef enum { CURLOPT(CURLOPT_HTTPHEADER, CURLOPTTYPE_SLISTPOINT, 23), /* This points to a linked list of post entries, struct curl_httppost */ - CURLOPT(CURLOPT_HTTPPOST, CURLOPTTYPE_OBJECTPOINT, 24), + CURLOPTDEPRECATED(CURLOPT_HTTPPOST, CURLOPTTYPE_OBJECTPOINT, 24, + 7.56.0, "Use CURLOPT_MIMEPOST"), /* name of the file keeping your private SSL-certificate */ CURLOPT(CURLOPT_SSLCERT, CURLOPTTYPE_STRINGPOINT, 25), @@ -1265,7 +1284,8 @@ typedef enum { CURLOPT(CURLOPT_TRANSFERTEXT, CURLOPTTYPE_LONG, 53), /* HTTP PUT */ - CURLOPT(CURLOPT_PUT, CURLOPTTYPE_LONG, 54), + CURLOPTDEPRECATED(CURLOPT_PUT, CURLOPTTYPE_LONG, 54, + 7.12.1, "Use CURLOPT_UPLOAD"), /* 55 = OBSOLETE */ @@ -1273,7 +1293,8 @@ typedef enum { * Function that will be called instead of the internal progress display * function. This function should be defined as the curl_progress_callback * prototype defines. */ - CURLOPT(CURLOPT_PROGRESSFUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 56), + CURLOPTDEPRECATED(CURLOPT_PROGRESSFUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 56, + 7.32.0, "Use CURLOPT_XFERINFOFUNCTION"), /* Data passed to the CURLOPT_PROGRESSFUNCTION and CURLOPT_XFERINFOFUNCTION callbacks */ @@ -1341,10 +1362,12 @@ typedef enum { /* Set to a file name that contains random data for libcurl to use to seed the random engine when doing SSL connects. */ - CURLOPT(CURLOPT_RANDOM_FILE, CURLOPTTYPE_STRINGPOINT, 76), + CURLOPTDEPRECATED(CURLOPT_RANDOM_FILE, CURLOPTTYPE_STRINGPOINT, 76, + 7.84.0, "Serves no purpose anymore"), /* Set to the Entropy Gathering Daemon socket pathname */ - CURLOPT(CURLOPT_EGDSOCKET, CURLOPTTYPE_STRINGPOINT, 77), + CURLOPTDEPRECATED(CURLOPT_EGDSOCKET, CURLOPTTYPE_STRINGPOINT, 77, + 7.84.0, "Serves no purpose anymore"), /* Time-out connect operations after this amount of seconds, if connects are OK within this time, then fine... This only aborts the connect phase. */ @@ -1399,7 +1422,8 @@ typedef enum { /* Non-zero value means to use the global dns cache */ /* DEPRECATED, do not use! */ - CURLOPT(CURLOPT_DNS_USE_GLOBAL_CACHE, CURLOPTTYPE_LONG, 91), + CURLOPTDEPRECATED(CURLOPT_DNS_USE_GLOBAL_CACHE, CURLOPTTYPE_LONG, 91, + 7.11.1, "Use CURLOPT_SHARE"), /* DNS cache timeout */ CURLOPT(CURLOPT_DNS_CACHE_TIMEOUT, CURLOPTTYPE_LONG, 92), @@ -1554,8 +1578,10 @@ typedef enum { */ CURLOPT(CURLOPT_FTPSSLAUTH, CURLOPTTYPE_VALUES, 129), - CURLOPT(CURLOPT_IOCTLFUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 130), - CURLOPT(CURLOPT_IOCTLDATA, CURLOPTTYPE_CBPOINT, 131), + CURLOPTDEPRECATED(CURLOPT_IOCTLFUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 130, + 7.18.0, "Use CURLOPT_SEEKFUNCTION"), + CURLOPTDEPRECATED(CURLOPT_IOCTLDATA, CURLOPTTYPE_CBPOINT, 131, + 7.18.0, "Use CURLOPT_SEEKDATA"), /* 132 OBSOLETE. Gone in 7.16.0 */ /* 133 OBSOLETE. Gone in 7.16.0 */ @@ -1594,16 +1620,22 @@ typedef enum { /* Function that will be called to convert from the network encoding (instead of using the iconv calls in libcurl) */ - CURLOPT(CURLOPT_CONV_FROM_NETWORK_FUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 142), + CURLOPTDEPRECATED(CURLOPT_CONV_FROM_NETWORK_FUNCTION, + CURLOPTTYPE_FUNCTIONPOINT, 142, + 7.82.0, "Serves no purpose anymore"), /* Function that will be called to convert to the network encoding (instead of using the iconv calls in libcurl) */ - CURLOPT(CURLOPT_CONV_TO_NETWORK_FUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 143), + CURLOPTDEPRECATED(CURLOPT_CONV_TO_NETWORK_FUNCTION, + CURLOPTTYPE_FUNCTIONPOINT, 143, + 7.82.0, "Serves no purpose anymore"), /* Function that will be called to convert from UTF8 (instead of using the iconv calls in libcurl) Note that this is used only for SSL certificate processing */ - CURLOPT(CURLOPT_CONV_FROM_UTF8_FUNCTION, CURLOPTTYPE_FUNCTIONPOINT, 144), + CURLOPTDEPRECATED(CURLOPT_CONV_FROM_UTF8_FUNCTION, + CURLOPTTYPE_FUNCTIONPOINT, 144, + 7.82.0, "Serves no purpose anymore"), /* if the connection proceeds too quickly then need to slow it down */ /* limit-rate: maximum number of bytes per second to send or receive */ @@ -1704,7 +1736,9 @@ typedef enum { /* Socks Service */ /* DEPRECATED, do not use! */ - CURLOPT(CURLOPT_SOCKS5_GSSAPI_SERVICE, CURLOPTTYPE_STRINGPOINT, 179), + CURLOPTDEPRECATED(CURLOPT_SOCKS5_GSSAPI_SERVICE, + CURLOPTTYPE_STRINGPOINT, 179, + 7.49.0, "Use CURLOPT_PROXY_SERVICE_NAME"), /* Socks Service */ CURLOPT(CURLOPT_SOCKS5_GSSAPI_NEC, CURLOPTTYPE_LONG, 180), @@ -1713,12 +1747,14 @@ typedef enum { transfer, which thus helps the app which takes URLs from users or other external inputs and want to restrict what protocol(s) to deal with. Defaults to CURLPROTO_ALL. */ - CURLOPT(CURLOPT_PROTOCOLS, CURLOPTTYPE_LONG, 181), + CURLOPTDEPRECATED(CURLOPT_PROTOCOLS, CURLOPTTYPE_LONG, 181, + 7.85.0, "Use CURLOPT_PROTOCOLS_STR"), /* set the bitmask for the protocols that libcurl is allowed to follow to, as a subset of the CURLOPT_PROTOCOLS ones. That means the protocol needs to be set in both bitmasks to be allowed to get redirected to. */ - CURLOPT(CURLOPT_REDIR_PROTOCOLS, CURLOPTTYPE_LONG, 182), + CURLOPTDEPRECATED(CURLOPT_REDIR_PROTOCOLS, CURLOPTTYPE_LONG, 182, + 7.85.0, "Use CURLOPT_REDIR_PROTOCOLS_STR"), /* set the SSH knownhost file name to use */ CURLOPT(CURLOPT_SSH_KNOWNHOSTS, CURLOPTTYPE_STRINGPOINT, 183), @@ -1863,7 +1899,8 @@ typedef enum { CURLOPT(CURLOPT_LOGIN_OPTIONS, CURLOPTTYPE_STRINGPOINT, 224), /* Enable/disable TLS NPN extension (http2 over ssl might fail without) */ - CURLOPT(CURLOPT_SSL_ENABLE_NPN, CURLOPTTYPE_LONG, 225), + CURLOPTDEPRECATED(CURLOPT_SSL_ENABLE_NPN, CURLOPTTYPE_LONG, 225, + 7.86.0, "Has no function"), /* Enable/disable TLS ALPN extension (http2 over ssl might fail without) */ CURLOPT(CURLOPT_SSL_ENABLE_ALPN, CURLOPTTYPE_LONG, 226), @@ -2451,30 +2488,32 @@ CURL_EXTERN CURLcode curl_mime_headers(curl_mimepart *part, int take_ownership); typedef enum { - CURLFORM_NOTHING, /********* the first one is unused ************/ - CURLFORM_COPYNAME, - CURLFORM_PTRNAME, - CURLFORM_NAMELENGTH, - CURLFORM_COPYCONTENTS, - CURLFORM_PTRCONTENTS, - CURLFORM_CONTENTSLENGTH, - CURLFORM_FILECONTENT, - CURLFORM_ARRAY, + /********* the first one is unused ************/ + CURLFORM_NOTHING CURL_DEPRECATED(7.56.0, ""), + CURLFORM_COPYNAME CURL_DEPRECATED(7.56.0, "Use curl_mime_name()"), + CURLFORM_PTRNAME CURL_DEPRECATED(7.56.0, "Use curl_mime_name()"), + CURLFORM_NAMELENGTH CURL_DEPRECATED(7.56.0, ""), + CURLFORM_COPYCONTENTS CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), + CURLFORM_PTRCONTENTS CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), + CURLFORM_CONTENTSLENGTH CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), + CURLFORM_FILECONTENT CURL_DEPRECATED(7.56.0, "Use curl_mime_data_cb()"), + CURLFORM_ARRAY CURL_DEPRECATED(7.56.0, ""), CURLFORM_OBSOLETE, - CURLFORM_FILE, + CURLFORM_FILE CURL_DEPRECATED(7.56.0, "Use curl_mime_filedata()"), - CURLFORM_BUFFER, - CURLFORM_BUFFERPTR, - CURLFORM_BUFFERLENGTH, + CURLFORM_BUFFER CURL_DEPRECATED(7.56.0, "Use curl_mime_filename()"), + CURLFORM_BUFFERPTR CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), + CURLFORM_BUFFERLENGTH CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), - CURLFORM_CONTENTTYPE, - CURLFORM_CONTENTHEADER, - CURLFORM_FILENAME, + CURLFORM_CONTENTTYPE CURL_DEPRECATED(7.56.0, "Use curl_mime_type()"), + CURLFORM_CONTENTHEADER CURL_DEPRECATED(7.56.0, "Use curl_mime_headers()"), + CURLFORM_FILENAME CURL_DEPRECATED(7.56.0, "Use curl_mime_filename()"), CURLFORM_END, CURLFORM_OBSOLETE2, - CURLFORM_STREAM, - CURLFORM_CONTENTLEN, /* added in 7.46.0, provide a curl_off_t length */ + CURLFORM_STREAM CURL_DEPRECATED(7.56.0, "Use curl_mime_data_cb()"), + CURLFORM_CONTENTLEN /* added in 7.46.0, provide a curl_off_t length */ + CURL_DEPRECATED(7.56.0, "Use curl_mime_data()"), CURLFORM_LASTENTRY /* the last unused */ } CURLformoption; @@ -2502,15 +2541,16 @@ struct curl_forms { * ***************************************************************************/ typedef enum { - CURL_FORMADD_OK, /* first, no error */ + CURL_FORMADD_OK CURL_DEPRECATED(7.56.0, ""), /* 1st, no error */ - CURL_FORMADD_MEMORY, - CURL_FORMADD_OPTION_TWICE, - CURL_FORMADD_NULL, - CURL_FORMADD_UNKNOWN_OPTION, - CURL_FORMADD_INCOMPLETE, - CURL_FORMADD_ILLEGAL_ARRAY, - CURL_FORMADD_DISABLED, /* libcurl was built with this disabled */ + CURL_FORMADD_MEMORY CURL_DEPRECATED(7.56.0, ""), + CURL_FORMADD_OPTION_TWICE CURL_DEPRECATED(7.56.0, ""), + CURL_FORMADD_NULL CURL_DEPRECATED(7.56.0, ""), + CURL_FORMADD_UNKNOWN_OPTION CURL_DEPRECATED(7.56.0, ""), + CURL_FORMADD_INCOMPLETE CURL_DEPRECATED(7.56.0, ""), + CURL_FORMADD_ILLEGAL_ARRAY CURL_DEPRECATED(7.56.0, ""), + /* libcurl was built with form api disabled */ + CURL_FORMADD_DISABLED CURL_DEPRECATED(7.56.0, ""), CURL_FORMADD_LAST /* last */ } CURLFORMcode; @@ -2524,9 +2564,10 @@ typedef enum { * adds one part that together construct a full post. Then use * CURLOPT_HTTPPOST to send it off to libcurl. */ -CURL_EXTERN CURLFORMcode curl_formadd(struct curl_httppost **httppost, - struct curl_httppost **last_post, - ...); +CURL_EXTERN CURLFORMcode CURL_DEPRECATED(7.56.0, "Use curl_mime_init()") +curl_formadd(struct curl_httppost **httppost, + struct curl_httppost **last_post, + ...); /* * callback function for curl_formget() @@ -2549,8 +2590,9 @@ typedef size_t (*curl_formget_callback)(void *arg, const char *buf, * the curl_formget_callback function. * Returns 0 on success. */ -CURL_EXTERN int curl_formget(struct curl_httppost *form, void *arg, - curl_formget_callback append); +CURL_EXTERN int CURL_DEPRECATED(7.56.0, "") +curl_formget(struct curl_httppost *form, void *arg, + curl_formget_callback append); /* * NAME curl_formfree() * @@ -2558,7 +2600,8 @@ CURL_EXTERN int curl_formget(struct curl_httppost *form, void *arg, * * Free a multipart formpost previously built with curl_formadd(). */ -CURL_EXTERN void curl_formfree(struct curl_httppost *form); +CURL_EXTERN void CURL_DEPRECATED(7.56.0, "Use curl_mime_free()") +curl_formfree(struct curl_httppost *form); /* * NAME curl_getenv() @@ -2785,22 +2828,35 @@ typedef enum { CURLINFO_NAMELOOKUP_TIME = CURLINFO_DOUBLE + 4, CURLINFO_CONNECT_TIME = CURLINFO_DOUBLE + 5, CURLINFO_PRETRANSFER_TIME = CURLINFO_DOUBLE + 6, - CURLINFO_SIZE_UPLOAD = CURLINFO_DOUBLE + 7, + CURLINFO_SIZE_UPLOAD CURL_DEPRECATED(7.55.0, "Use CURLINFO_SIZE_UPLOAD_T") + = CURLINFO_DOUBLE + 7, CURLINFO_SIZE_UPLOAD_T = CURLINFO_OFF_T + 7, - CURLINFO_SIZE_DOWNLOAD = CURLINFO_DOUBLE + 8, + CURLINFO_SIZE_DOWNLOAD + CURL_DEPRECATED(7.55.0, "Use CURLINFO_SIZE_DOWNLOAD_T") + = CURLINFO_DOUBLE + 8, CURLINFO_SIZE_DOWNLOAD_T = CURLINFO_OFF_T + 8, - CURLINFO_SPEED_DOWNLOAD = CURLINFO_DOUBLE + 9, + CURLINFO_SPEED_DOWNLOAD + CURL_DEPRECATED(7.55.0, "Use CURLINFO_SPEED_DOWNLOAD_T") + = CURLINFO_DOUBLE + 9, CURLINFO_SPEED_DOWNLOAD_T = CURLINFO_OFF_T + 9, - CURLINFO_SPEED_UPLOAD = CURLINFO_DOUBLE + 10, + CURLINFO_SPEED_UPLOAD + CURL_DEPRECATED(7.55.0, "Use CURLINFO_SPEED_UPLOAD_T") + = CURLINFO_DOUBLE + 10, CURLINFO_SPEED_UPLOAD_T = CURLINFO_OFF_T + 10, CURLINFO_HEADER_SIZE = CURLINFO_LONG + 11, CURLINFO_REQUEST_SIZE = CURLINFO_LONG + 12, CURLINFO_SSL_VERIFYRESULT = CURLINFO_LONG + 13, CURLINFO_FILETIME = CURLINFO_LONG + 14, CURLINFO_FILETIME_T = CURLINFO_OFF_T + 14, - CURLINFO_CONTENT_LENGTH_DOWNLOAD = CURLINFO_DOUBLE + 15, + CURLINFO_CONTENT_LENGTH_DOWNLOAD + CURL_DEPRECATED(7.55.0, + "Use CURLINFO_CONTENT_LENGTH_DOWNLOAD_T") + = CURLINFO_DOUBLE + 15, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T = CURLINFO_OFF_T + 15, - CURLINFO_CONTENT_LENGTH_UPLOAD = CURLINFO_DOUBLE + 16, + CURLINFO_CONTENT_LENGTH_UPLOAD + CURL_DEPRECATED(7.55.0, + "Use CURLINFO_CONTENT_LENGTH_UPLOAD_T") + = CURLINFO_DOUBLE + 16, CURLINFO_CONTENT_LENGTH_UPLOAD_T = CURLINFO_OFF_T + 16, CURLINFO_STARTTRANSFER_TIME = CURLINFO_DOUBLE + 17, CURLINFO_CONTENT_TYPE = CURLINFO_STRING + 18, @@ -2814,7 +2870,8 @@ typedef enum { CURLINFO_NUM_CONNECTS = CURLINFO_LONG + 26, CURLINFO_SSL_ENGINES = CURLINFO_SLIST + 27, CURLINFO_COOKIELIST = CURLINFO_SLIST + 28, - CURLINFO_LASTSOCKET = CURLINFO_LONG + 29, + CURLINFO_LASTSOCKET CURL_DEPRECATED(7.45.0, "Use CURLINFO_ACTIVESOCKET") + = CURLINFO_LONG + 29, CURLINFO_FTP_ENTRY_PATH = CURLINFO_STRING + 30, CURLINFO_REDIRECT_URL = CURLINFO_STRING + 31, CURLINFO_PRIMARY_IP = CURLINFO_STRING + 32, @@ -2828,12 +2885,14 @@ typedef enum { CURLINFO_PRIMARY_PORT = CURLINFO_LONG + 40, CURLINFO_LOCAL_IP = CURLINFO_STRING + 41, CURLINFO_LOCAL_PORT = CURLINFO_LONG + 42, - CURLINFO_TLS_SESSION = CURLINFO_PTR + 43, + CURLINFO_TLS_SESSION CURL_DEPRECATED(7.48.0, "Use CURLINFO_TLS_SSL_PTR") + = CURLINFO_PTR + 43, CURLINFO_ACTIVESOCKET = CURLINFO_SOCKET + 44, CURLINFO_TLS_SSL_PTR = CURLINFO_PTR + 45, CURLINFO_HTTP_VERSION = CURLINFO_LONG + 46, CURLINFO_PROXY_SSL_VERIFYRESULT = CURLINFO_LONG + 47, - CURLINFO_PROTOCOL = CURLINFO_LONG + 48, + CURLINFO_PROTOCOL CURL_DEPRECATED(7.85.0, "Use CURLINFO_SCHEME") + = CURLINFO_LONG + 48, CURLINFO_SCHEME = CURLINFO_STRING + 49, CURLINFO_TOTAL_TIME_T = CURLINFO_OFF_T + 50, CURLINFO_NAMELOOKUP_TIME_T = CURLINFO_OFF_T + 51, diff --git a/include/curl/multi.h b/include/curl/multi.h index 2f3ec37a7685a9..c956d28e8f2230 100644 --- a/include/curl/multi.h +++ b/include/curl/multi.h @@ -318,16 +318,16 @@ typedef int (*curl_multi_timer_callback)(CURLM *multi, /* multi handle */ void *userp); /* private callback pointer */ -CURL_EXTERN CURLMcode curl_multi_socket(CURLM *multi_handle, curl_socket_t s, - int *running_handles); +CURL_EXTERN CURLMcode CURL_DEPRECATED(7.19.5, "Use curl_multi_socket_action()") +curl_multi_socket(CURLM *multi_handle, curl_socket_t s, int *running_handles); CURL_EXTERN CURLMcode curl_multi_socket_action(CURLM *multi_handle, curl_socket_t s, int ev_bitmask, int *running_handles); -CURL_EXTERN CURLMcode curl_multi_socket_all(CURLM *multi_handle, - int *running_handles); +CURL_EXTERN CURLMcode CURL_DEPRECATED(7.19.5, "Use curl_multi_socket_action()") +curl_multi_socket_all(CURLM *multi_handle, int *running_handles); #ifndef CURL_ALLOW_OLD_MULTI_SOCKET /* This macro below was added in 7.16.3 to push users who recompile to use diff --git a/include/curl/typecheck-gcc.h b/include/curl/typecheck-gcc.h index 00961dbc3dc1cd..bf655bb63220d5 100644 --- a/include/curl/typecheck-gcc.h +++ b/include/curl/typecheck-gcc.h @@ -42,107 +42,113 @@ */ #define curl_easy_setopt(handle, option, value) \ __extension__({ \ - __typeof__(option) _curl_opt = option; \ + CURL_IGNORE_DEPRECATION(__typeof__(option) _curl_opt = option;) \ if(__builtin_constant_p(_curl_opt)) { \ - if(curlcheck_long_option(_curl_opt)) \ - if(!curlcheck_long(value)) \ - _curl_easy_setopt_err_long(); \ - if(curlcheck_off_t_option(_curl_opt)) \ - if(!curlcheck_off_t(value)) \ - _curl_easy_setopt_err_curl_off_t(); \ - if(curlcheck_string_option(_curl_opt)) \ - if(!curlcheck_string(value)) \ - _curl_easy_setopt_err_string(); \ - if(curlcheck_write_cb_option(_curl_opt)) \ - if(!curlcheck_write_cb(value)) \ - _curl_easy_setopt_err_write_callback(); \ - if((_curl_opt) == CURLOPT_RESOLVER_START_FUNCTION) \ - if(!curlcheck_resolver_start_callback(value)) \ - _curl_easy_setopt_err_resolver_start_callback(); \ - if((_curl_opt) == CURLOPT_READFUNCTION) \ - if(!curlcheck_read_cb(value)) \ - _curl_easy_setopt_err_read_cb(); \ - if((_curl_opt) == CURLOPT_IOCTLFUNCTION) \ - if(!curlcheck_ioctl_cb(value)) \ - _curl_easy_setopt_err_ioctl_cb(); \ - if((_curl_opt) == CURLOPT_SOCKOPTFUNCTION) \ - if(!curlcheck_sockopt_cb(value)) \ - _curl_easy_setopt_err_sockopt_cb(); \ - if((_curl_opt) == CURLOPT_OPENSOCKETFUNCTION) \ - if(!curlcheck_opensocket_cb(value)) \ - _curl_easy_setopt_err_opensocket_cb(); \ - if((_curl_opt) == CURLOPT_PROGRESSFUNCTION) \ - if(!curlcheck_progress_cb(value)) \ - _curl_easy_setopt_err_progress_cb(); \ - if((_curl_opt) == CURLOPT_DEBUGFUNCTION) \ - if(!curlcheck_debug_cb(value)) \ - _curl_easy_setopt_err_debug_cb(); \ - if((_curl_opt) == CURLOPT_SSL_CTX_FUNCTION) \ - if(!curlcheck_ssl_ctx_cb(value)) \ - _curl_easy_setopt_err_ssl_ctx_cb(); \ - if(curlcheck_conv_cb_option(_curl_opt)) \ - if(!curlcheck_conv_cb(value)) \ - _curl_easy_setopt_err_conv_cb(); \ - if((_curl_opt) == CURLOPT_SEEKFUNCTION) \ - if(!curlcheck_seek_cb(value)) \ - _curl_easy_setopt_err_seek_cb(); \ - if(curlcheck_cb_data_option(_curl_opt)) \ - if(!curlcheck_cb_data(value)) \ - _curl_easy_setopt_err_cb_data(); \ - if((_curl_opt) == CURLOPT_ERRORBUFFER) \ - if(!curlcheck_error_buffer(value)) \ - _curl_easy_setopt_err_error_buffer(); \ - if((_curl_opt) == CURLOPT_STDERR) \ - if(!curlcheck_FILE(value)) \ - _curl_easy_setopt_err_FILE(); \ - if(curlcheck_postfields_option(_curl_opt)) \ - if(!curlcheck_postfields(value)) \ - _curl_easy_setopt_err_postfields(); \ - if((_curl_opt) == CURLOPT_HTTPPOST) \ - if(!curlcheck_arr((value), struct curl_httppost)) \ - _curl_easy_setopt_err_curl_httpost(); \ - if((_curl_opt) == CURLOPT_MIMEPOST) \ - if(!curlcheck_ptr((value), curl_mime)) \ - _curl_easy_setopt_err_curl_mimepost(); \ - if(curlcheck_slist_option(_curl_opt)) \ - if(!curlcheck_arr((value), struct curl_slist)) \ - _curl_easy_setopt_err_curl_slist(); \ - if((_curl_opt) == CURLOPT_SHARE) \ - if(!curlcheck_ptr((value), CURLSH)) \ - _curl_easy_setopt_err_CURLSH(); \ + (void) option; \ + CURL_IGNORE_DEPRECATION( \ + if(curlcheck_long_option(_curl_opt)) \ + if(!curlcheck_long(value)) \ + _curl_easy_setopt_err_long(); \ + if(curlcheck_off_t_option(_curl_opt)) \ + if(!curlcheck_off_t(value)) \ + _curl_easy_setopt_err_curl_off_t(); \ + if(curlcheck_string_option(_curl_opt)) \ + if(!curlcheck_string(value)) \ + _curl_easy_setopt_err_string(); \ + if(curlcheck_write_cb_option(_curl_opt)) \ + if(!curlcheck_write_cb(value)) \ + _curl_easy_setopt_err_write_callback(); \ + if((_curl_opt) == CURLOPT_RESOLVER_START_FUNCTION) \ + if(!curlcheck_resolver_start_callback(value)) \ + _curl_easy_setopt_err_resolver_start_callback(); \ + if((_curl_opt) == CURLOPT_READFUNCTION) \ + if(!curlcheck_read_cb(value)) \ + _curl_easy_setopt_err_read_cb(); \ + if((_curl_opt) == CURLOPT_IOCTLFUNCTION) \ + if(!curlcheck_ioctl_cb(value)) \ + _curl_easy_setopt_err_ioctl_cb(); \ + if((_curl_opt) == CURLOPT_SOCKOPTFUNCTION) \ + if(!curlcheck_sockopt_cb(value)) \ + _curl_easy_setopt_err_sockopt_cb(); \ + if((_curl_opt) == CURLOPT_OPENSOCKETFUNCTION) \ + if(!curlcheck_opensocket_cb(value)) \ + _curl_easy_setopt_err_opensocket_cb(); \ + if((_curl_opt) == CURLOPT_PROGRESSFUNCTION) \ + if(!curlcheck_progress_cb(value)) \ + _curl_easy_setopt_err_progress_cb(); \ + if((_curl_opt) == CURLOPT_DEBUGFUNCTION) \ + if(!curlcheck_debug_cb(value)) \ + _curl_easy_setopt_err_debug_cb(); \ + if((_curl_opt) == CURLOPT_SSL_CTX_FUNCTION) \ + if(!curlcheck_ssl_ctx_cb(value)) \ + _curl_easy_setopt_err_ssl_ctx_cb(); \ + if(curlcheck_conv_cb_option(_curl_opt)) \ + if(!curlcheck_conv_cb(value)) \ + _curl_easy_setopt_err_conv_cb(); \ + if((_curl_opt) == CURLOPT_SEEKFUNCTION) \ + if(!curlcheck_seek_cb(value)) \ + _curl_easy_setopt_err_seek_cb(); \ + if(curlcheck_cb_data_option(_curl_opt)) \ + if(!curlcheck_cb_data(value)) \ + _curl_easy_setopt_err_cb_data(); \ + if((_curl_opt) == CURLOPT_ERRORBUFFER) \ + if(!curlcheck_error_buffer(value)) \ + _curl_easy_setopt_err_error_buffer(); \ + if((_curl_opt) == CURLOPT_STDERR) \ + if(!curlcheck_FILE(value)) \ + _curl_easy_setopt_err_FILE(); \ + if(curlcheck_postfields_option(_curl_opt)) \ + if(!curlcheck_postfields(value)) \ + _curl_easy_setopt_err_postfields(); \ + if((_curl_opt) == CURLOPT_HTTPPOST) \ + if(!curlcheck_arr((value), struct curl_httppost)) \ + _curl_easy_setopt_err_curl_httpost(); \ + if((_curl_opt) == CURLOPT_MIMEPOST) \ + if(!curlcheck_ptr((value), curl_mime)) \ + _curl_easy_setopt_err_curl_mimepost(); \ + if(curlcheck_slist_option(_curl_opt)) \ + if(!curlcheck_arr((value), struct curl_slist)) \ + _curl_easy_setopt_err_curl_slist(); \ + if((_curl_opt) == CURLOPT_SHARE) \ + if(!curlcheck_ptr((value), CURLSH)) \ + _curl_easy_setopt_err_CURLSH(); \ + ) \ } \ curl_easy_setopt(handle, _curl_opt, value); \ }) /* wraps curl_easy_getinfo() with typechecking */ #define curl_easy_getinfo(handle, info, arg) \ - __extension__({ \ - __typeof__(info) _curl_info = info; \ + __extension__({ \ + CURL_IGNORE_DEPRECATION(__typeof__(info) _curl_info = info;) \ if(__builtin_constant_p(_curl_info)) { \ - if(curlcheck_string_info(_curl_info)) \ - if(!curlcheck_arr((arg), char *)) \ - _curl_easy_getinfo_err_string(); \ - if(curlcheck_long_info(_curl_info)) \ - if(!curlcheck_arr((arg), long)) \ - _curl_easy_getinfo_err_long(); \ - if(curlcheck_double_info(_curl_info)) \ - if(!curlcheck_arr((arg), double)) \ - _curl_easy_getinfo_err_double(); \ - if(curlcheck_slist_info(_curl_info)) \ - if(!curlcheck_arr((arg), struct curl_slist *)) \ - _curl_easy_getinfo_err_curl_slist(); \ - if(curlcheck_tlssessioninfo_info(_curl_info)) \ - if(!curlcheck_arr((arg), struct curl_tlssessioninfo *)) \ - _curl_easy_getinfo_err_curl_tlssesssioninfo(); \ - if(curlcheck_certinfo_info(_curl_info)) \ - if(!curlcheck_arr((arg), struct curl_certinfo *)) \ - _curl_easy_getinfo_err_curl_certinfo(); \ - if(curlcheck_socket_info(_curl_info)) \ - if(!curlcheck_arr((arg), curl_socket_t)) \ - _curl_easy_getinfo_err_curl_socket(); \ - if(curlcheck_off_t_info(_curl_info)) \ - if(!curlcheck_arr((arg), curl_off_t)) \ - _curl_easy_getinfo_err_curl_off_t(); \ + (void) info; \ + CURL_IGNORE_DEPRECATION( \ + if(curlcheck_string_info(_curl_info)) \ + if(!curlcheck_arr((arg), char *)) \ + _curl_easy_getinfo_err_string(); \ + if(curlcheck_long_info(_curl_info)) \ + if(!curlcheck_arr((arg), long)) \ + _curl_easy_getinfo_err_long(); \ + if(curlcheck_double_info(_curl_info)) \ + if(!curlcheck_arr((arg), double)) \ + _curl_easy_getinfo_err_double(); \ + if(curlcheck_slist_info(_curl_info)) \ + if(!curlcheck_arr((arg), struct curl_slist *)) \ + _curl_easy_getinfo_err_curl_slist(); \ + if(curlcheck_tlssessioninfo_info(_curl_info)) \ + if(!curlcheck_arr((arg), struct curl_tlssessioninfo *)) \ + _curl_easy_getinfo_err_curl_tlssesssioninfo(); \ + if(curlcheck_certinfo_info(_curl_info)) \ + if(!curlcheck_arr((arg), struct curl_certinfo *)) \ + _curl_easy_getinfo_err_curl_certinfo(); \ + if(curlcheck_socket_info(_curl_info)) \ + if(!curlcheck_arr((arg), curl_socket_t)) \ + _curl_easy_getinfo_err_curl_socket(); \ + if(curlcheck_off_t_info(_curl_info)) \ + if(!curlcheck_arr((arg), curl_off_t)) \ + _curl_easy_getinfo_err_curl_off_t(); \ + ) \ } \ curl_easy_getinfo(handle, _curl_info, arg); \ }) diff --git a/tests/Makefile.am b/tests/Makefile.am index 829e125d25735a..5da7423244afa9 100644 --- a/tests/Makefile.am +++ b/tests/Makefile.am @@ -34,7 +34,8 @@ EXTRA_DIST = ftpserver.pl httpserver.pl secureserver.pl runtests.pl \ manpage-scan.pl nroff-scan.pl http2-server.pl dictserver.py \ negtelnetserver.py smbserver.py util.py \ disable-scan.pl manpage-syntax.pl error-codes.pl badsymbols.pl \ - azure.pm appveyor.pm version-scan.pl options-scan.pl markdown-uppercase.pl + azure.pm appveyor.pm version-scan.pl options-scan.pl markdown-uppercase.pl \ + check-deprecated.pl DISTCLEANFILES = configurehelp.pm diff --git a/tests/badsymbols.pl b/tests/badsymbols.pl index 392b190f8f7d54..205a4f5c72ed5b 100755 --- a/tests/badsymbols.pl +++ b/tests/badsymbols.pl @@ -74,7 +74,8 @@ sub scanenums { my ($file)=@_; my $skipit = 0; - open H_IN, "-|", "$Cpreprocessor $i$file" || die "Cannot preprocess $file"; + open H_IN, "-|", "$Cpreprocessor -DCURL_DISABLE_DEPRECATION $i$file" || + die "Cannot preprocess $file"; while ( ) { my ($line, $linenum) = ($_, $.); if( /^#(line|) (\d+) \"(.*)\"/) { @@ -102,6 +103,7 @@ sub scanenums { if(($_ !~ /\}(;|)/) && ($_ ne "typedef") && ($_ ne "enum") && + ($_ ne "=") && ($_ !~ /^[ \t]*$/)) { if($verbose) { print "Source: $Cpreprocessor $i$file\n"; diff --git a/tests/check-deprecated.pl b/tests/check-deprecated.pl new file mode 100755 index 00000000000000..ab1bc495367a47 --- /dev/null +++ b/tests/check-deprecated.pl @@ -0,0 +1,330 @@ +#!/usr/bin/env perl +#*************************************************************************** +# _ _ ____ _ +# Project ___| | | | _ \| | +# / __| | | | |_) | | +# | (__| |_| | _ <| |___ +# \___|\___/|_| \_\_____| +# +# Copyright (C) 2016 - 2022, 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 +# are also available at https://curl.se/docs/copyright.html. +# +# You may opt to use, copy, modify, merge, publish, distribute and/or sell +# copies of the Software, and permit persons to whom the Software is +# furnished to do so, under the terms of the COPYING file. +# +# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +# KIND, either express or implied. +# +# SPDX-License-Identifier: curl +# +# +########################################################################### +# +# Check that the deprecated statuses of functions and enum values in header +# files, man pages and symbols-in-versions are in sync. + +use strict; +use warnings; + +use File::Basename; + +my $root=$ARGV[0] || "."; +my $incdir = "$root/include/curl"; +my $docdir = "$root/docs"; +my $libdocdir = "$docdir/libcurl"; +my $errcode = 0; + +# Symbol-indexed hashes. +# Values are: +# X Not deprecated +# ? Deprecated in unknown version +# x.yy.z Deprecated in version x.yy.z +my %syminver; # Symbols-in-versions deprecations. +my %hdr; # Public header files deprecations. +my %funcman; # Function man pages deprecations. +my %optman; # Option man pages deprecations. + + +# Scan header file for public function and enum values. Flag them with +# the version they are deprecated in, if some. +sub scan_header { + my ($f)=@_; + my $line = ""; + my $incomment = 0; + my $inenum = 0; + + open H, "<$f"; + while() { + s/^\s*(.*?)\s*$/$1/; # Trim. + # Remove multi-line comment trail. + if($incomment) { + if($_ !~ /.*?\*\/\s*(.*)$/) { + next; + } + $_ = $1; + $incomment = 0; + } + if($line ne "") { + # Unfold line. + $_ = "$line $1"; + $line = ""; + } + # Remove comments. + while($_ =~ /^(.*?)\/\*.*?\*\/(.*)$/) { + $_ = "$1 $2"; + } + if($_ =~ /^(.*)\/\*/) { + $_ = "$1 "; + $incomment = 1; + } + s/^\s*(.*?)\s*$/$1/; # Trim again. + # Ignore preprocessor directives and blank lines. + if($_ =~ /^(?:#|$)/) { + next; + } + # Handle lines that may be continued as if they were folded. + if($_ !~ /[;,{}]$/) { + # Folded line. + $line = $_; + next; + } + if($_ =~ /CURLOPTDEPRECATED\(/) { + # Handle deprecated CURLOPT_* option. + if($_ !~ /CURLOPTDEPRECATED\(\s*(\S+)\s*,(?:.*?,){2}\s*(.*?)\s*,.*"\)/) { + # Folded line. + $line = $_; + next; + } + $hdr{$1} = $2; + } + elsif($_ =~ /CURLOPT\(/) { + # Handle non-deprecated CURLOPT_* option. + if($_ !~ /CURLOPT\(\s*(\S+)\s*(?:,.*?){2}\)/) { + # Folded line. + $line = $_; + next; + } + $hdr{$1} = "X"; + } + else { + my $version = "X"; + + # Get other kind of deprecation from this line. + if($_ =~ /CURL_DEPRECATED\(/) { + if($_ !~ /^(.*)CURL_DEPRECATED\(\s*(\S+?)\s*,.*?"\)(.*)$/) { + # Folded line. + $line = $_; + next; + } + $version = $2; + $_ = "$1 $3"; + } + if($_ =~ /^CURL_EXTERN\s+.*\s+(\S+?)\s*\(/) { + # Flag public function. + $hdr{$1} = $version; + } + elsif($inenum && $_ =~ /(\w+)\s*[,=}]/) { + # Flag enum value. + $hdr{$1} = $version; + } + } + # Remember if we are in an enum definition. + $inenum |= ($_ =~ /\benum\b/); + if($_ =~ /}/) { + $inenum = 0; + } + } + close H; +} + +# Scan function man page for options. +# Each option has to be declared as ".IP