Wala shell

Advanced PHP File Manager

Server IP: 127.0.0.1 | PHP Version: 8.3.30 | Domains Hosted: 54

Name	Size	Last Modified
📁 ..	-	2026-03-31 19:08
📄 CURLINFO_ACTIVESOCKET.3 .\" generated by cd2nroff 0.1 from CURLINFO_ACTIVESOCKET.md .TH CURLINFO_ACTIVESOCKET 3 "2025-06-27" libcurl .SH NAME CURLINFO_ACTIVESOCKET \- get the active socket .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_ACTIVESOCKET, curl_socket_t socket); .fi .SH DESCRIPTION Pass a pointer to a curl_socket_t to receive the most recently active socket used for the transfer connection by this curl session. If the socket is no longer valid, \fICURL_SOCKET_BAD\fP is returned. When you are finished working with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual on the easy handle and let libcurl close the socket and cleanup other resources associated with the handle. This option returns the active socket only after the transfer is complete, and is typically used in combination with \fICURLOPT_CONNECT_ONLY(3)\fP, which skips the transfer phase. \fICURLINFO_ACTIVESOCKET(3)\fP was added as a replacement for \fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_socket_t sockfd; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Do not do the transfer - only connect to host / curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); res = curl_easy_perform(curl); if(res != CURLE_OK) { printf("Error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); return 1; } / Extract the socket from the curl handle / res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); if(!res && sockfd != CURL_SOCKET_BAD) { / operate on sockfd */ } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.45.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LASTSOCKET (3), .BR CURLOPT_CONNECT_ONLY (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	2.14 KB	2025-07-08 09:41
📄 CURLINFO_APPCONNECT_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_APPCONNECT_TIME.md .TH CURLINFO_APPCONNECT_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_APPCONNECT_TIME \- get the time until the SSL/SSH handshake is completed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_APPCONNECT_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the time, in seconds, it took from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(3)\fP time, except for cases such as HTTP multiplexing where the pretransfer time can be delayed due to waits in line for the stream and more. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double connect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME, &connect); if(CURLE_OK == res) { printf("Time: %.1f", connect); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_APPCONNECT_TIME_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.71 KB	2025-07-08 09:41
📄 CURLINFO_APPCONNECT_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_APPCONNECT_TIME_T.md .TH CURLINFO_APPCONNECT_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_APPCONNECT_TIME_T \- time until the SSL/SSH handshake completed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_APPCONNECT_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the time, in microseconds, it took from the start until the SSL/SSH connect/handshake to the remote host was completed. This time is most often close to the \fICURLINFO_PRETRANSFER_TIME_T(3)\fP time, except for cases such as HTTP multiplexing where the pretransfer time can be delayed due to waits in line for the stream and more. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t connect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_APPCONNECT_TIME_T, &connect); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, (long)(connect % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_APPCONNECT_TIME (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.8 KB	2025-07-08 09:41
📄 CURLINFO_CAINFO.3 .\" generated by cd2nroff 0.1 from CURLINFO_CAINFO.md .TH CURLINFO_CAINFO 3 "2025-06-27" libcurl .SH NAME CURLINFO_CAINFO \- get the default built\-in CA certificate path .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CAINFO, char path); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to a null\-terminated string holding the default built\-in path used for the \fICURLOPT_CAINFO(3)\fP option unless set by the user. Note that in a situation where libcurl has been built to support multiple TLS libraries, this option might return a string even if the specific TLS library currently set to be used does not support \fICURLOPT_CAINFO(3)\fP. This is a path identifying a single file containing CA certificates. The \fBpath\fP pointer is set to NULL if there is no default path. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { char *cainfo = NULL; curl_easy_getinfo(curl, CURLINFO_CAINFO, &cainfo); if(cainfo) { printf("default ca info path: %s\\n", cainfo); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.84.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAPATH (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.56 KB	2025-07-08 09:41
📄 CURLINFO_CAPATH.3 .\" generated by cd2nroff 0.1 from CURLINFO_CAPATH.md .TH CURLINFO_CAPATH 3 "2025-06-27" libcurl .SH NAME CURLINFO_CAPATH \- get the default built\-in CA path string .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CAPATH, char path); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to a null\-terminated string holding the default built\-in path used for the \fICURLOPT_CAPATH(3)\fP option unless set by the user. Note that in a situation where libcurl has been built to support multiple TLS libraries, this option might return a string even if the specific TLS library currently set to be used does not support \fICURLOPT_CAPATH(3)\fP. This is a path identifying a directory. The \fBpath\fP pointer is set to NULL if there is no default path. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { char *capath = NULL; curl_easy_getinfo(curl, CURLINFO_CAPATH, &capath); if(capath) { printf("default ca path: %s\\n", capath); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.84.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAINFO (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.57 KB	2025-07-08 09:41
📄 CURLINFO_CERTINFO.3 .\" generated by cd2nroff 0.1 from CURLINFO_CERTINFO.md .TH CURLINFO_CERTINFO 3 "2025-06-27" libcurl .SH NAME CURLINFO_CERTINFO \- get the TLS certificate chain .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CERTINFO, struct curl_certinfo chainp); .fi .SH DESCRIPTION Pass a pointer to a \fIstruct curl_certinfo \fP and it is set to point to a struct that holds info about the server\(aqs certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was made. .nf struct curl_certinfo { int num_of_certs; struct curl_slist *certinfo; }; .fi The \fIcertinfo\fP struct member is an array of linked lists of certificate information. The \fInum_of_certs\fP struct member is the number of certificates which is the number of elements in the array. Each certificate\(aqs list has items with textual information in the format "name:content" such as \&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on the SSL backend and the certificate. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport and rustls .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); /* connect to any HTTPS site, trusted or not / curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); res = curl_easy_perform(curl); if(!res) { int i; struct curl_certinfo ci; res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); if(!res) { printf("%d certs!\\n", ci->num_of_certs); for(i = 0; i < ci->num_of_certs; i++) { struct curl_slist *slist; for(slist = ci->certinfo[i]; slist; slist = slist->next) printf("%s\\n", slist->data); } } } curl_easy_cleanup(curl); } } .fi See also the \fIcertinfo.c\fP example. .SH HISTORY GnuTLS support added in 7.42.0. Schannel support added in 7.50.0. Secure Transport support added in 7.79.0. mbedTLS support added in 8.9.0. .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAPATH (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	2.6 KB	2025-07-08 09:41
📄 CURLINFO_CONDITION_UNMET.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONDITION_UNMET.md .TH CURLINFO_CONDITION_UNMET 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONDITION_UNMET \- get info on unmet time conditional or 304 HTTP response. .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONDITION_UNMET, long unmet); .fi .SH DESCRIPTION Pass a pointer to a long to receive the number 1 if the condition provided in the previous request did not match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas, if this returns a 1 you know that the reason you did not get data in return is because it did not fulfill the condition. The long this argument points to gets a zero stored if the condition instead was met. This can also return 1 if the server responded with a 304 HTTP status code, for example after sending a custom "If\-Match\-" header. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* January 1, 2020 is 1577833200 / curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); / If-Modified-Since the above time stamp / curl_easy_setopt(curl, CURLOPT_TIMECONDITION, (long)CURL_TIMECOND_IFMODSINCE); / Perform the request / res = curl_easy_perform(curl); if(!res) { / check the time condition */ long unmet; res = curl_easy_getinfo(curl, CURLINFO_CONDITION_UNMET, &unmet); if(!res) { printf("The time condition was %sfulfilled\\n", unmet?"NOT":""); } } } } .fi .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TIMECONDITION (3), .BR CURLOPT_TIMEVALUE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.98 KB	2025-07-08 09:41
📄 CURLINFO_CONNECT_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONNECT_TIME.md .TH CURLINFO_CONNECT_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONNECT_TIME \- get the time until connect .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONNECT_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total time in seconds from the start until the connection to the remote host (or proxy) was completed. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double connect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME, &connect); if(CURLE_OK == res) { printf("Time: %.1f", connect); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONNECT_TIME_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.42 KB	2025-07-08 09:41
📄 CURLINFO_CONNECT_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONNECT_TIME_T.md .TH CURLINFO_CONNECT_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONNECT_TIME_T \- get the time until connect .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONNECT_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the total time in microseconds from the start until the connection to the remote host (or proxy) was completed. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t connect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_CONNECT_TIME_T, &connect); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", connect / 1000000, (long)(connect % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONNECT_TIME (3), .BR CURLOPT_CONNECTTIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.59 KB	2025-07-08 09:41
📄 CURLINFO_CONN_ID.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONN_ID.md .TH CURLINFO_CONN_ID 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONN_ID \- get the ID of the last connection used by the handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONN_ID, curl_off_t conn_id); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the connection identifier last used by the handle. Stores \-1 if there was no connection used. The connection id is unique among all connections using the same connection cache. This is implicitly the case for all connections in the same multi handle. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t conn_id; res = curl_easy_getinfo(curl, CURLINFO_CONN_ID, &conn_id); if(!res) { printf("Connection used: %" CURL_FORMAT_CURL_OFF_T "\\n", conn_id); } } } } .fi .SH AVAILABILITY Added in curl 8.2.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_XFER_ID (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.46 KB	2025-07-08 09:41
📄 CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_DOWNLOAD.md .TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONTENT_LENGTH_DOWNLOAD \- get content\-length of download .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD, double content_length); .fi .SH DESCRIPTION Pass a pointer to a double to receive the content\-length of the download. This is the value read from the Content\-Length: field. Since 7.19.4, this returns -1 if the size is not known. \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request / res = curl_easy_perform(curl); if(!res) { / check the size */ double cl; res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD, &cl); if(!res) { printf("Size: %.0f\\n", cl); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.6.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_UPLOAD (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.54 KB	2025-07-08 09:41
📄 CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.md .TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONTENT_LENGTH_DOWNLOAD_T \- get content\-length of download .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, curl_off_t content_length); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the content\-length of the download. This is the value read from the Content\-Length: field. Stores \-1 if the size is not known. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request / res = curl_easy_perform(curl); if(!res) { / check the size */ curl_off_t cl; res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_DOWNLOAD_T, &cl); if(!res) { printf("Download size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.42 KB	2025-07-08 09:41
📄 CURLINFO_CONTENT_LENGTH_UPLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_UPLOAD.md .TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONTENT_LENGTH_UPLOAD \- get the specified size of the upload .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONTENT_LENGTH_UPLOAD, double content_length); .fi .SH DESCRIPTION Pass a pointer to a double to receive the specified size of the upload. Since 7.19.4, this returns \-1 if the size is not known. \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the upload / res = curl_easy_perform(curl); if(!res) { / check the size */ double cl; res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD, &cl); if(!res) { printf("Size: %.0f\\n", cl); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.6.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.48 KB	2025-07-08 09:41
📄 CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_LENGTH_UPLOAD_T.md .TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONTENT_LENGTH_UPLOAD_T \- get the specified size of the upload .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONTENT_LENGTH_UPLOAD_T, curl_off_t content_length); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the specified size of the upload. Stores \-1 if the size is not known. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the upload / res = curl_easy_perform(curl); if(!res) { / check the size */ curl_off_t cl; res = curl_easy_getinfo(curl, CURLINFO_CONTENT_LENGTH_UPLOAD_T, &cl); if(!res) { printf("Upload size: %" CURL_FORMAT_CURL_OFF_T "\\n", cl); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_DOWNLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.37 KB	2025-07-08 09:41
📄 CURLINFO_CONTENT_TYPE.3 .\" generated by cd2nroff 0.1 from CURLINFO_CONTENT_TYPE.md .TH CURLINFO_CONTENT_TYPE 3 "2025-06-27" libcurl .SH NAME CURLINFO_CONTENT_TYPE \- get Content\-Type .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_CONTENT_TYPE, char ct); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the content\-type of the downloaded object. This is the value read from the Content\-Type: field. If you get NULL, it means that the server did not send a valid Content\-Type header or that the protocol used does not support this. The \fBct\fP pointer is set to NULL or pointing to private memory. You MUST NOT free it \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. The modern way to get this header from a response is to instead use the \fIcurl_easy_header(3)\fP function. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(!res) { /* extract the content-type / char ct = NULL; res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); if(!res && ct) { printf("Content-Type: %s\\n", ct); } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.4 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADERFUNCTION (3), .BR curl_easy_getinfo (3), .BR curl_easy_header (3), .BR curl_easy_setopt (3)	1.69 KB	2025-07-08 09:41
📄 CURLINFO_COOKIELIST.3 .\" generated by cd2nroff 0.1 from CURLINFO_COOKIELIST.md .TH CURLINFO_COOKIELIST 3 "2025-06-27" libcurl .SH NAME CURLINFO_COOKIELIST \- get all known cookies .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_COOKIELIST, struct curl_slist cookies); .fi .SH DESCRIPTION Pass a pointer to a \(aqstruct curl_slist \(aq to receive a linked\-list of all cookies curl knows (expired ones, too). Do not forget to call \fIcurl_slist_free_all(3)\fP on the list after it has been used. If there are no cookies (cookies for the handle have not been enabled or simply none have been received) the \(aqstruct curl_slist \(aq is made a NULL pointer. Since 7.43.0 cookies that were imported in the Set\-Cookie format without a domain name are not exported by this option. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable the cookie engine / curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); res = curl_easy_perform(curl); if(!res) { / extract all known cookies / struct curl_slist cookies = NULL; res = curl_easy_getinfo(curl, CURLINFO_COOKIELIST, &cookies); if(!res && cookies) { /* a linked list of cookies in cookie file format / struct curl_slist each = cookies; while(each) { printf("%s\\n", each->data); each = each->next; } /* we must free these cookies when we are done */ curl_slist_free_all(cookies); } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.14.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COOKIELIST (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.99 KB	2025-07-08 09:41
📄 CURLINFO_EARLYDATA_SENT_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_EARLYDATA_SENT_T.md .TH CURLINFO_EARLYDATA_SENT_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_EARLYDATA_SENT_T \- get the number of bytes sent as TLS early data .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_EARLYDATA_SENT_T, curl_off_t amount); .fi .SH DESCRIPTION Pass a pointer to an \fIcurl_off_t\fP to receive the total amount of bytes that were sent to the server as TLSv1.3 early data. When no TLS early data is used, this reports 0. TLS early data is only attempted when CURLSSLOPT_EARLYDATA is set for the transfer. In addition, it is only used by libcurl when a TLS session exists that announces support. The amount is \fBnegative\fP when the sent data was rejected by the server. TLS allows a server that announces support for early data to reject any attempt to use it at its own discretion. When for example 127 bytes had been sent, but were rejected, it reports \-127 as the amount "sent". .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t amount; res = curl_easy_getinfo(curl, CURLINFO_EARLYDATA_SENT_T, &amount); if(!res) { printf("TLS earlydata: %" CURL_FORMAT_CURL_OFF_T " bytes\\n", amount); } } } } .fi .SH AVAILABILITY Added in curl 8.11.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.9 KB	2025-07-08 09:41
📄 CURLINFO_EFFECTIVE_METHOD.3 .\" generated by cd2nroff 0.1 from CURLINFO_EFFECTIVE_METHOD.md .TH CURLINFO_EFFECTIVE_METHOD 3 "2025-06-27" libcurl .SH NAME CURLINFO_EFFECTIVE_METHOD \- get the last used HTTP method .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_EFFECTIVE_METHOD, char methodp); .fi .SH DESCRIPTION Pass in a pointer to a char pointer and get the last used effective HTTP method. In cases when you have asked libcurl to follow redirects, the method may not be the same method the first request would use. The \fBmethodp\fP pointer is NULL or points to private memory. You MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { char *method = NULL; curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_METHOD, &method); if(method) printf("Redirected to method: %s\\n", method); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.72.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.66 KB	2025-07-08 09:41
📄 CURLINFO_EFFECTIVE_URL.3 .\" generated by cd2nroff 0.1 from CURLINFO_EFFECTIVE_URL.md .TH CURLINFO_EFFECTIVE_URL 3 "2025-06-27" libcurl .SH NAME CURLINFO_EFFECTIVE_URL \- get the last used URL .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_EFFECTIVE_URL, char urlp); .fi .SH DESCRIPTION Pass in a pointer to a char pointer and get the last used effective URL. In cases when you have asked libcurl to follow redirects, it may not be the same value you set with \fICURLOPT_URL(3)\fP. The \fBurlp\fP pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { char *url = NULL; curl_easy_getinfo(curl, CURLINFO_EFFECTIVE_URL, &url); if(url) printf("Redirect to: %s\\n", url); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FOLLOWLOCATION (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.48 KB	2025-07-08 09:41
📄 CURLINFO_FILETIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_FILETIME.md .TH CURLINFO_FILETIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_FILETIME \- get the remote time of the retrieved document .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_FILETIME, long timep); .fi .SH DESCRIPTION Pass a pointer to a long to receive the remote time of the retrieved document in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get -1, it can be because of many reasons (it might be unknown, the server might hide it or the server does not support the command that tells document time etc) and the time of the document is unknown. You must ask libcurl to collect this information before the transfer is made, by using the \fICURLOPT_FILETIME(3)\fP option or you unconditionally get a \-1 back. Consider \fICURLINFO_FILETIME_T(3)\fP instead to be able to extract dates beyond the year 2038 on systems using 32\-bit longs (Windows). .SH PROTOCOLS This functionality affects ftp, http and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Ask for filetime / curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); res = curl_easy_perform(curl); if(CURLE_OK == res) { long filetime = 0; res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); if((CURLE_OK == res) && (filetime >= 0)) { time_t file_time = (time_t)filetime; printf("filetime: %s", ctime(&file_time)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.5 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FILETIME (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.92 KB	2025-07-08 09:41
📄 CURLINFO_FILETIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_FILETIME_T.md .TH CURLINFO_FILETIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_FILETIME_T \- get the remote time of the retrieved document .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_FILETIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the remote time of the retrieved document in number of seconds since January 1 1970 in the GMT/UTC time zone. If you get \-1, it can be because of many reasons (it might be unknown, the server might hide it or the server does not support the command that tells document time etc) and the time of the document is unknown. You must ask libcurl to collect this information before the transfer is made, by using the \fICURLOPT_FILETIME(3)\fP option or you unconditionally get a \-1 back. This option is an alternative to \fICURLINFO_FILETIME(3)\fP to allow systems with 32 bit long variables to extract dates outside of the 32\-bit timestamp range. .SH PROTOCOLS This functionality affects ftp, http and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / Ask for filetime / curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); res = curl_easy_perform(curl); if(CURLE_OK == res) { curl_off_t filetime; res = curl_easy_getinfo(curl, CURLINFO_FILETIME_T, &filetime); if((CURLE_OK == res) && (filetime >= 0)) { time_t file_time = (time_t)filetime; printf("filetime: %s", ctime(&file_time)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.59.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FILETIME (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	2 KB	2025-07-08 09:41
📄 CURLINFO_FTP_ENTRY_PATH.3 .\" generated by cd2nroff 0.1 from CURLINFO_FTP_ENTRY_PATH.md .TH CURLINFO_FTP_ENTRY_PATH 3 "2025-06-27" libcurl .SH NAME CURLINFO_FTP_ENTRY_PATH \- get entry path in FTP server .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_FTP_ENTRY_PATH, char path); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive a pointer to a string holding the path of the entry path. That is the initial path libcurl ended up in when logging on to the remote FTP server. This stores a NULL as pointer if something is wrong. The \fBpath\fP pointer is NULL or points to private memory. You MUST NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); res = curl_easy_perform(curl); if(!res) { /* extract the entry path / char ep = NULL; res = curl_easy_getinfo(curl, CURLINFO_FTP_ENTRY_PATH, &ep); if(!res && ep) { printf("Entry path was: %s\\n", ep); } } curl_easy_cleanup(curl); } } .fi .SH HISTORY Works for SFTP since 7.21.4 .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.54 KB	2025-07-08 09:41
📄 CURLINFO_HEADER_SIZE.3 .\" generated by cd2nroff 0.1 from CURLINFO_HEADER_SIZE.md .TH CURLINFO_HEADER_SIZE 3 "2025-06-27" libcurl .SH NAME CURLINFO_HEADER_SIZE \- get size of retrieved headers .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_HEADER_SIZE, long sizep); .fi .SH DESCRIPTION Pass a pointer to a long to receive the total size of all the headers received. Measured in number of bytes. The total includes the size of any received headers suppressed by \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long size; res = curl_easy_getinfo(curl, CURLINFO_HEADER_SIZE, &size); if(!res) printf("Header size: %ld bytes\\n", size); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REQUEST_SIZE (3), .BR CURLINFO_SIZE_DOWNLOAD (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.34 KB	2025-07-08 09:41
📄 CURLINFO_HTTPAUTH_AVAIL.3 .\" generated by cd2nroff 0.1 from CURLINFO_HTTPAUTH_AVAIL.md .TH CURLINFO_HTTPAUTH_AVAIL 3 "2025-06-27" libcurl .SH NAME CURLINFO_HTTPAUTH_AVAIL \- get available HTTP authentication methods .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_HTTPAUTH_AVAIL, long authp); .fi .SH DESCRIPTION Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available according to the previous response. The meaning of the bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(!res) { / extract the available authentication types */ long auth; res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth); if(!res) { if(!auth) printf("No auth available, perhaps no 401?\\n"); else { printf("%s%s%s%s\\n", auth & CURLAUTH_BASIC ? "Basic ":"", auth & CURLAUTH_DIGEST ? "Digest ":"", auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", auth % CURLAUTH_NTLM ? "NTLM ":""); } } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.8 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PROXYAUTH_AVAIL (3), .BR CURLOPT_HTTPAUTH (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.72 KB	2025-07-08 09:41
📄 CURLINFO_HTTPAUTH_USED.3 .\" generated by cd2nroff 0.1 from CURLINFO_HTTPAUTH_USED.md .TH CURLINFO_HTTPAUTH_USED 3 "2025-06-27" libcurl .SH NAME CURLINFO_HTTPAUTH_USED \- get used HTTP authentication method .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_HTTPAUTH_USED, long authp); .fi .SH DESCRIPTION Pass a pointer to a long to receive a bitmask indicating the authentication method that was used in the previous HTTP request. The meaning of the possible bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. The returned value has zero or one bit set. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC \| CURLAUTH_DIGEST); curl_easy_setopt(curl, CURLOPT_USERNAME, "shrek"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "swamp"); res = curl_easy_perform(curl); if(!res) { long auth; res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_USED, &auth); if(!res) { if(!auth) printf("No auth used\\n"); else { if(auth == CURLAUTH_DIGEST) printf("Used Digest authentication\\n"); else printf("Used Basic authentication\\n"); } } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.12.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_HTTPAUTH_AVAIL (3), .BR CURLINFO_PROXYAUTH_USED (3), .BR CURLOPT_HTTPAUTH (3)	1.75 KB	2025-07-08 09:41
📄 CURLINFO_HTTP_CONNECTCODE.3 .\" generated by cd2nroff 0.1 from CURLINFO_HTTP_CONNECTCODE.md .TH CURLINFO_HTTP_CONNECTCODE 3 "2025-06-27" libcurl .SH NAME CURLINFO_HTTP_CONNECTCODE \- get the CONNECT response code .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_HTTP_CONNECTCODE, long p); .fi .SH DESCRIPTION Pass a pointer to a long to receive the last received HTTP proxy response code to a CONNECT request. The returned value is zero if no such response code was available. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / typically CONNECT is used to do HTTPS over HTTP proxies */ curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long code; res = curl_easy_getinfo(curl, CURLINFO_HTTP_CONNECTCODE, &code); if(!res && code) printf("The CONNECT response code: %03ld\\n", code); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.7 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.41 KB	2025-07-08 09:41
📄 CURLINFO_HTTP_VERSION.3 .\" generated by cd2nroff 0.1 from CURLINFO_HTTP_VERSION.md .TH CURLINFO_HTTP_VERSION 3 "2025-06-27" libcurl .SH NAME CURLINFO_HTTP_VERSION \- get the http version used in the connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_HTTP_VERSION, long p); .fi .SH DESCRIPTION Pass a pointer to a long to receive the version used in the last http connection done using this handle. The returned value is CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the version cannot be determined. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long http_version; curl_easy_getinfo(curl, CURLINFO_HTTP_VERSION, &http_version); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.50.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.29 KB	2025-07-08 09:41
📄 CURLINFO_LASTSOCKET.3 .\" generated by cd2nroff 0.1 from CURLINFO_LASTSOCKET.md .TH CURLINFO_LASTSOCKET 3 "2025-06-27" libcurl .SH NAME CURLINFO_LASTSOCKET \- get the last socket used .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_LASTSOCKET, long socket); .fi .SH DESCRIPTION Deprecated since 7.45.0. Use \fICURLINFO_ACTIVESOCKET(3)\fP instead. Pass a pointer to a long to receive the last socket used by this curl session. If the socket is no longer valid, \-1 is returned. When you finish working with the socket, you must call \fIcurl_easy_cleanup(3)\fP as usual and let libcurl close the socket and cleanup other resources associated with the handle. This is typically used in combination with \fICURLOPT_CONNECT_ONLY(3)\fP. NOTE: this API is deprecated since it is not working on win64 where the SOCKET type is 64 bits large while its \(aqlong\(aq is 32 bits. Use the \fICURLINFO_ACTIVESOCKET(3)\fP instead, if possible. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; long sockfd; / does not work on win64 / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Do not do the transfer - only connect to host / curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); res = curl_easy_perform(curl); if(res != CURLE_OK) { printf("Error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); return 1; } / Extract the socket from the curl handle / res = curl_easy_getinfo(curl, CURLINFO_LASTSOCKET, &sockfd); if(!res && sockfd != -1) { / operate on sockfd */ } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.2 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_ACTIVESOCKET (3), .BR CURLOPT_CONNECT_ONLY (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	2.04 KB	2025-07-08 09:41
📄 CURLINFO_LOCAL_IP.3 .\" generated by cd2nroff 0.1 from CURLINFO_LOCAL_IP.md .TH CURLINFO_LOCAL_IP 3 "2025-06-27" libcurl .SH NAME CURLINFO_LOCAL_IP \- get local IP address of last connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_LOCAL_IP, char ip); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to a null\-terminated string holding the IP address of the local end of most recent connection done with this \fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you get a pointer to a memory area that is reused at next request so you need to copy the string if you want to keep the information. The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding CURL handle. .SH PROTOCOLS This functionality affects quic and tcp .SH EXAMPLE .nf int main(void) { char ip; CURLcode res; CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the transfer / res = curl_easy_perform(curl); / Check for errors / if((res == CURLE_OK) && !curl_easy_getinfo(curl, CURLINFO_LOCAL_IP, &ip) && ip) { printf("Local IP: %s\\n", ip); } / always cleanup */ curl_easy_cleanup(curl); } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LOCAL_PORT (3), .BR CURLINFO_PRIMARY_IP (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.65 KB	2025-07-08 09:41
📄 CURLINFO_LOCAL_PORT.3 .\" generated by cd2nroff 0.1 from CURLINFO_LOCAL_PORT.md .TH CURLINFO_LOCAL_PORT 3 "2025-06-27" libcurl .SH NAME CURLINFO_LOCAL_PORT \- get the latest local port number .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_LOCAL_PORT, long portp); .fi .SH DESCRIPTION Pass a pointer to a long to receive the local port number of the most recent connection done with this \fBcurl\fP handle. If the connection was done using QUIC, the port number is a UDP port number, otherwise it is a TCP port number. .SH PROTOCOLS This functionality affects quic and tcp .SH EXAMPLE .nf int main(void) { CURL *curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { long port; res = curl_easy_getinfo(curl, CURLINFO_LOCAL_PORT, &port); if(CURLE_OK == res) { printf("We used local port: %ld\\n", port); } } curl_easy_cleanup(curl); } return 0; } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LOCAL_IP (3), .BR CURLINFO_PRIMARY_PORT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.38 KB	2025-07-08 09:41
📄 CURLINFO_NAMELOOKUP_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_NAMELOOKUP_TIME.md .TH CURLINFO_NAMELOOKUP_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_NAMELOOKUP_TIME \- get the name lookup time .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_NAMELOOKUP_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total time in seconds from the start until the name resolving was completed. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double namelookup; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME, &namelookup); if(CURLE_OK == res) { printf("Time: %.1f", namelookup); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_NAMELOOKUP_TIME_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.45 KB	2025-07-08 09:41
📄 CURLINFO_NAMELOOKUP_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_NAMELOOKUP_TIME_T.md .TH CURLINFO_NAMELOOKUP_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_NAMELOOKUP_TIME_T \- get the name lookup time in microseconds .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_NAMELOOKUP_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the total time in microseconds from the start until the name resolving was completed. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t namelookup; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_NAMELOOKUP_TIME_T, &namelookup); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", namelookup / 1000000, (long)(namelookup % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_NAMELOOKUP_TIME (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.57 KB	2025-07-08 09:41
📄 CURLINFO_NUM_CONNECTS.3 .\" generated by cd2nroff 0.1 from CURLINFO_NUM_CONNECTS.md .TH CURLINFO_NUM_CONNECTS 3 "2025-06-27" libcurl .SH NAME CURLINFO_NUM_CONNECTS \- get number of created connections .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_NUM_CONNECTS, long nump); .fi .SH DESCRIPTION Pass a pointer to a long to receive how many new connections libcurl had to create to achieve the previous transfer (only the successful connects are counted). Combined with \fICURLINFO_REDIRECT_COUNT(3)\fP you are able to know how many times libcurl successfully reused existing connection(s) or not. See the connection options of \fIcurl_easy_setopt(3)\fP to see how libcurl tries to make persistent connections to save time. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { long connects; res = curl_easy_getinfo(curl, CURLINFO_NUM_CONNECTS, &connects); if(!res) printf("It needed %ld connects\\n", connects); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.12.3 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.55 KB	2025-07-08 09:41
📄 CURLINFO_OS_ERRNO.3 .\" generated by cd2nroff 0.1 from CURLINFO_OS_ERRNO.md .TH CURLINFO_OS_ERRNO 3 "2025-06-27" libcurl .SH NAME CURLINFO_OS_ERRNO \- get errno number from last connect failure .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_OS_ERRNO, long errnop); .fi .SH DESCRIPTION Pass a pointer to a long to receive the errno variable from a connect failure. Note that the value is only set on failure, it is not reset upon a successful operation. The number is OS and system specific. libcurl network\-related errors that may have a saved errno are: CURLE_COULDNT_CONNECT, CURLE_FAILED_INIT, CURLE_INTERFACE_FAILED, CURLE_OPERATION_TIMEDOUT, CURLE_RECV_ERROR, CURLE_SEND_ERROR. Since 8.8.0 libcurl clears the easy handle\(aqs saved errno before performing the transfer. Prior versions did not clear the saved errno, which means if a saved errno is retrieved it could be from a previous transfer on the same handle. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res != CURLE_OK) { long error; res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error); if(!res && error) { printf("Errno: %ld\\n", error); } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.12.2 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.69 KB	2025-07-08 09:41
📄 CURLINFO_POSTTRANSFER_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_POSTTRANSFER_TIME_T.md .TH CURLINFO_POSTTRANSFER_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_POSTTRANSFER_TIME_T \- get the time until the last byte is sent .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_POSTTRANSFER_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the time, in microseconds, it took from the start until the last byte is sent by libcurl. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { curl_off_t posttransfer; res = curl_easy_getinfo(curl, CURLINFO_POSTTRANSFER_TIME_T, &posttransfer); if(CURLE_OK == res) { printf("Request sent after: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", posttransfer / 1000000, (long)(posttransfer % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.10.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRETRANSFER_TIME_T (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.67 KB	2025-07-08 09:41
📄 CURLINFO_PRETRANSFER_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_PRETRANSFER_TIME.md .TH CURLINFO_PRETRANSFER_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_PRETRANSFER_TIME \- get the time until the file transfer start .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PRETRANSFER_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the time, in seconds, it took from the start until the file transfer is just about to begin. This time\-stamp includes all pre\-transfer commands and negotiations that are specific to the particular protocol(s) involved. It includes the sending of the protocol\-specific instructions that trigger a transfer. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double pretransfer; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME, &pretransfer); if(CURLE_OK == res) { printf("Time: %.1f", pretransfer); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONNECT_TIME_T (3), .BR CURLINFO_PRETRANSFER_TIME_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.73 KB	2025-07-08 09:41
📄 CURLINFO_PRETRANSFER_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_PRETRANSFER_TIME_T.md .TH CURLINFO_PRETRANSFER_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_PRETRANSFER_TIME_T \- get the time until the file transfer start .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PRETRANSFER_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the time, in microseconds, it took from the start until the file transfer is just about to begin. This time\-stamp includes all pre\-transfer commands and negotiations that are specific to the particular protocol(s) involved. It includes the sending of the protocol\-specific instructions that trigger a transfer. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t pretransfer; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_PRETRANSFER_TIME_T, &pretransfer); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld\\n", pretransfer / 1000000, (long)(pretransfer % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONNECT_TIME (3), .BR CURLINFO_PRETRANSFER_TIME_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.86 KB	2025-07-08 09:41
📄 CURLINFO_PRIMARY_IP.3 .\" generated by cd2nroff 0.1 from CURLINFO_PRIMARY_IP.md .TH CURLINFO_PRIMARY_IP 3 "2025-06-27" libcurl .SH NAME CURLINFO_PRIMARY_IP \- get IP address of last connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PRIMARY_IP, char ip); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to a null\-terminated string holding the IP address of the most recent connection done with this \fBcurl\fP handle. This string may be IPv6 when that is enabled. Note that you get a pointer to a memory area that is reused at next request so you need to copy the string if you want to keep the information. The \fBip\fP pointer is NULL or points to private memory. You MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { char ip; CURLcode res; CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the transfer / res = curl_easy_perform(curl); / Check for errors / if((res == CURLE_OK) && !curl_easy_getinfo(curl, CURLINFO_PRIMARY_IP, &ip) && ip) { printf("IP: %s\\n", ip); } / always cleanup */ curl_easy_cleanup(curl); } .fi .SH AVAILABILITY Added in curl 7.19.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LOCAL_IP (3), .BR CURLINFO_LOCAL_PORT (3), .BR CURLINFO_PRIMARY_PORT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.67 KB	2025-07-08 09:41
📄 CURLINFO_PRIMARY_PORT.3 .\" generated by cd2nroff 0.1 from CURLINFO_PRIMARY_PORT.md .TH CURLINFO_PRIMARY_PORT 3 "2025-06-27" libcurl .SH NAME CURLINFO_PRIMARY_PORT \- get the latest destination port number .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PRIMARY_PORT, long portp); .fi .SH DESCRIPTION Pass a pointer to a long to receive the destination port of the most recent connection done with this \fBcurl\fP handle. This is the destination port of the actual TCP or UDP connection libcurl used. If a proxy was used for the most recent transfer, this is the port number of the proxy, if no proxy was used it is the port number of the most recently accessed URL. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long port; res = curl_easy_getinfo(curl, CURLINFO_PRIMARY_PORT, &port); if(!res) printf("Connected to remote port: %ld\\n", port); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LOCAL_PORT (3), .BR CURLINFO_PRIMARY_IP (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.5 KB	2025-07-08 09:41
📄 CURLINFO_PRIVATE.3 .\" generated by cd2nroff 0.1 from CURLINFO_PRIVATE.md .TH CURLINFO_PRIVATE 3 "2025-06-27" libcurl .SH NAME CURLINFO_PRIVATE \- get the private pointer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PRIVATE, char private); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to the private data associated with the curl handle (set with the \fICURLOPT_PRIVATE(3)\fP). Please note that for internal reasons, the value is returned as a char pointer, although effectively being a \(aqvoid \(aq. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; void pointer = (void )0x2345454; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); / set the private pointer / curl_easy_setopt(curl, CURLOPT_PRIVATE, pointer); res = curl_easy_perform(curl); / extract the private pointer again */ res = curl_easy_getinfo(curl, CURLINFO_PRIVATE, &pointer); if(res) printf("error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PRIVATE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.46 KB	2025-07-08 09:41
📄 CURLINFO_PROTOCOL.3 .\" generated by cd2nroff 0.1 from CURLINFO_PROTOCOL.md .TH CURLINFO_PROTOCOL 3 "2025-06-27" libcurl .SH NAME CURLINFO_PROTOCOL \- get the protocol used in the connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PROTOCOL, long p); .fi .SH DESCRIPTION This option is deprecated. We strongly recommend using \fICURLINFO_SCHEME(3)\fP instead, because this option cannot return all possible protocols. Pass a pointer to a long to receive the version used in the last http connection. The returned value is set to one of these values: .nf CURLPROTO_DICT, CURLPROTO_FILE, CURLPROTO_FTP, CURLPROTO_FTPS, CURLPROTO_GOPHER, CURLPROTO_HTTP, CURLPROTO_HTTPS, CURLPROTO_IMAP, CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3, CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS, CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT .fi .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long protocol; curl_easy_getinfo(curl, CURLINFO_PROTOCOL, &protocol); } curl_easy_cleanup(curl); } } .fi .SH DEPRECATED Deprecated since 7.85.0. .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.81 KB	2025-07-08 09:41
📄 CURLINFO_PROXYAUTH_AVAIL.3 .\" generated by cd2nroff 0.1 from CURLINFO_PROXYAUTH_AVAIL.md .TH CURLINFO_PROXYAUTH_AVAIL 3 "2025-06-27" libcurl .SH NAME CURLINFO_PROXYAUTH_AVAIL \- get available HTTP proxy authentication methods .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PROXYAUTH_AVAIL, long authp); .fi .SH DESCRIPTION Pass a pointer to a long to receive a bitmask indicating the authentication method(s) available according to the previous response. The meaning of the bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); res = curl_easy_perform(curl); if(!res) { / extract the available proxy authentication types */ long auth; res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth); if(!res) { if(!auth) printf("No proxy auth available, perhaps no 407?\\n"); else { printf("%s%s%s%s\\n", auth & CURLAUTH_BASIC ? "Basic ":"", auth & CURLAUTH_DIGEST ? "Digest ":"", auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"", auth % CURLAUTH_NTLM ? "NTLM ":""); } } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.8 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_HTTPAUTH_AVAIL (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.81 KB	2025-07-08 09:41
📄 CURLINFO_PROXYAUTH_USED.3 .\" generated by cd2nroff 0.1 from CURLINFO_PROXYAUTH_USED.md .TH CURLINFO_PROXYAUTH_USED 3 "2025-06-27" libcurl .SH NAME CURLINFO_PROXYAUTH_USED \- get used HTTP proxy authentication method .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PROXYAUTH_USED, long authp); .fi .SH DESCRIPTION Pass a pointer to a long to receive a bitmask indicating the authentication method that was used in the previous request done over an HTTP proxy. The meaning of the possible bits is explained in the \fICURLOPT_HTTPAUTH(3)\fP option for \fIcurl_easy_setopt(3)\fP. The returned value has zero or one bit set. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com"); curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_BASIC \| CURLAUTH_DIGEST); curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "shrek"); curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "swamp"); res = curl_easy_perform(curl); if(!res) { long auth; res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_USED, &auth); if(!res) { if(!auth) printf("No auth used\\n"); else { if(auth == CURLAUTH_DIGEST) printf("Used Digest proxy authentication\\n"); else printf("Used Basic proxy authentication\\n"); } } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.12.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_HTTPAUTH_USED (3), .BR CURLINFO_PROXYAUTH_AVAIL (3), .BR CURLOPT_HTTPAUTH (3)	1.9 KB	2025-07-08 09:41
📄 CURLINFO_PROXY_ERROR.3 .\" generated by cd2nroff 0.1 from CURLINFO_PROXY_ERROR.md .TH CURLINFO_PROXY_ERROR 3 "2025-06-27" libcurl .SH NAME CURLINFO_PROXY_ERROR \- get the detailed (SOCKS) proxy error .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLPX_OK, CURLPX_BAD_ADDRESS_TYPE, CURLPX_BAD_VERSION, CURLPX_CLOSED, CURLPX_GSSAPI, CURLPX_GSSAPI_PERMSG, CURLPX_GSSAPI_PROTECTION, CURLPX_IDENTD, CURLPX_IDENTD_DIFFER, CURLPX_LONG_HOSTNAME, CURLPX_LONG_PASSWD, CURLPX_LONG_USER, CURLPX_NO_AUTH, CURLPX_RECV_ADDRESS, CURLPX_RECV_AUTH, CURLPX_RECV_CONNECT, CURLPX_RECV_REQACK, CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED, CURLPX_REPLY_COMMAND_NOT_SUPPORTED, CURLPX_REPLY_CONNECTION_REFUSED, CURLPX_REPLY_GENERAL_SERVER_FAILURE, CURLPX_REPLY_HOST_UNREACHABLE, CURLPX_REPLY_NETWORK_UNREACHABLE, CURLPX_REPLY_NOT_ALLOWED, CURLPX_REPLY_TTL_EXPIRED, CURLPX_REPLY_UNASSIGNED, CURLPX_REQUEST_FAILED, CURLPX_RESOLVE_HOST, CURLPX_SEND_AUTH, CURLPX_SEND_CONNECT, CURLPX_SEND_REQUEST, CURLPX_UNKNOWN_FAIL, CURLPX_UNKNOWN_MODE, CURLPX_USER_REJECTED, CURLPX_LAST /* never use / } CURLproxycode; CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PROXY_ERROR, long detail); .fi .SH DESCRIPTION Pass a pointer to a long to receive a detailed error code when the most recent transfer returned a \fBCURLE_PROXY\fP error. That error code matches the \fBCURLproxycode\fP set. The error code is zero (\fBCURLPX_OK\fP) if no response code was available. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://127.0.0.1"); res = curl_easy_perform(curl); if(res == CURLE_PROXY) { long proxycode; res = curl_easy_getinfo(curl, CURLINFO_PROXY_ERROR, &proxycode); if(!res && proxycode) printf("The detailed proxy error: %ld\\n", proxycode); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.73.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3), .BR libcurl-errors (3)	2.37 KB	2025-07-08 09:41
📄 CURLINFO_PROXY_SSL_VERIFYRESULT.3 .\" generated by cd2nroff 0.1 from CURLINFO_PROXY_SSL_VERIFYRESULT.md .TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "2025-06-27" libcurl .SH NAME CURLINFO_PROXY_SSL_VERIFYRESULT \- get the result of the proxy certificate verification .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_PROXY_SSL_VERIFYRESULT, long result); .fi .SH DESCRIPTION Pass a pointer to a long to receive the result of the certificate verification that was requested (using the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. This is only used for HTTPS proxies. 0 is a positive result. Non\-zero is an error. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; long verifyresult; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); res = curl_easy_perform(curl); if(res) { printf("error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); return 1; } res = curl_easy_getinfo(curl, CURLINFO_PROXY_SSL_VERIFYRESULT, &verifyresult); if(!res) { printf("The peer verification said %s\\n", (verifyresult ? "bad" : "fine")); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SSL_VERIFYRESULT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.79 KB	2025-07-08 09:41
📄 CURLINFO_QUEUE_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_QUEUE_TIME_T.md .TH CURLINFO_QUEUE_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_QUEUE_TIME_T \- time this transfer was queued .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_QUEUE_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the time, in microseconds, this transfer was held in a waiting queue before it started "for real". A transfer might be put in a queue if after getting started, it cannot create a new connection etc due to set conditions and limits imposed by the application. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t queue; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_QUEUE_TIME_T, &queue); if(CURLE_OK == res) { printf("Queued: %" CURL_FORMAT_CURL_OFF_T ".%06ld us", queue / 1000000, (long)(queue % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.6.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_STARTTRANSFER_TIME_T (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.65 KB	2025-07-08 09:41
📄 CURLINFO_REDIRECT_COUNT.3 .\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_COUNT.md .TH CURLINFO_REDIRECT_COUNT 3 "2025-06-27" libcurl .SH NAME CURLINFO_REDIRECT_COUNT \- get the number of redirects .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REDIRECT_COUNT, long countp); .fi .SH DESCRIPTION Pass a pointer to a long to receive the total number of redirections that were actually followed. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { long redirects; curl_easy_getinfo(curl, CURLINFO_REDIRECT_COUNT, &redirects); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.7 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_URL (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.25 KB	2025-07-08 09:41
📄 CURLINFO_REDIRECT_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_TIME.md .TH CURLINFO_REDIRECT_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_REDIRECT_TIME \- get the time for all redirection steps .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REDIRECT_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total time, in seconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. \fICURLINFO_REDIRECT_TIME(3)\fP contains the complete execution time for multiple redirections. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double redirect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME, &redirect); if(CURLE_OK == res) { printf("Time: %.1f", redirect); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.7 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLINFO_REDIRECT_TIME_T (3), .BR CURLINFO_REDIRECT_URL (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.59 KB	2025-07-08 09:41
📄 CURLINFO_REDIRECT_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_TIME_T.md .TH CURLINFO_REDIRECT_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_REDIRECT_TIME_T \- get the time for all redirection steps .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REDIRECT_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the total time, in microseconds, it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. \fICURLINFO_REDIRECT_TIME_T(3)\fP holds the complete execution time for multiple redirections. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t redirect; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_REDIRECT_TIME_T, &redirect); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", redirect / 1000000, (long)(redirect % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLINFO_REDIRECT_TIME (3), .BR CURLINFO_REDIRECT_URL (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.69 KB	2025-07-08 09:41
📄 CURLINFO_REDIRECT_URL.3 .\" generated by cd2nroff 0.1 from CURLINFO_REDIRECT_URL.md .TH CURLINFO_REDIRECT_URL 3 "2025-06-27" libcurl .SH NAME CURLINFO_REDIRECT_URL \- get the URL a redirect would go to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REDIRECT_URL, char urlp); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the URL a redirect \fIwould\fP take you to if you would enable \fICURLOPT_FOLLOWLOCATION(3)\fP. This can come handy if you think using the built\-in libcurl redirect logic is not good enough for you but you would still prefer to avoid implementing all the magic of figuring out the new URL. This URL is also set if the \fICURLOPT_MAXREDIRS(3)\fP limit prevented a redirect to happen (since 7.54.1). .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { char *url = NULL; curl_easy_getinfo(curl, CURLINFO_REDIRECT_URL, &url); if(url) printf("Redirect to: %s\\n", url); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.18.2 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLINFO_REDIRECT_TIME_T (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.58 KB	2025-07-08 09:41
📄 CURLINFO_REFERER.3 .\" generated by cd2nroff 0.1 from CURLINFO_REFERER.md .TH CURLINFO_REFERER 3 "2025-06-27" libcurl .SH NAME CURLINFO_REFERER \- get the used referrer request header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REFERER, char hdrp); .fi .SH DESCRIPTION Pass in a pointer to a char pointer and get the referrer header used in the most recent request. The \fBhdrp\fP pointer is NULL or points to private memory you MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/referrer"); res = curl_easy_perform(curl); if(res == CURLE_OK) { char *hdr = NULL; curl_easy_getinfo(curl, CURLINFO_REFERER, &hdr); if(hdr) printf("Referrer header: %s\\n", hdr); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.76.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_REFERER (3), .BR curl_easy_getinfo (3), .BR curl_easy_header (3), .BR curl_easy_setopt (3)	1.42 KB	2025-07-08 09:41
📄 CURLINFO_REQUEST_SIZE.3 .\" generated by cd2nroff 0.1 from CURLINFO_REQUEST_SIZE.md .TH CURLINFO_REQUEST_SIZE 3 "2025-06-27" libcurl .SH NAME CURLINFO_REQUEST_SIZE \- get size of sent request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_REQUEST_SIZE, long sizep); .fi .SH DESCRIPTION Pass a pointer to a long to receive the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long req; res = curl_easy_getinfo(curl, CURLINFO_REQUEST_SIZE, &req); if(!res) printf("Request size: %ld bytes\\n", req); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_HEADER_SIZE (3), .BR CURLINFO_SIZE_DOWNLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.32 KB	2025-07-08 09:41
📄 CURLINFO_RESPONSE_CODE.3 .\" generated by cd2nroff 0.1 from CURLINFO_RESPONSE_CODE.md .TH CURLINFO_RESPONSE_CODE 3 "2025-06-27" libcurl .SH NAME CURLINFO_RESPONSE_CODE \- get the last response code .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RESPONSE_CODE, long codep); .fi .SH DESCRIPTION Pass a pointer to a long to receive the last received HTTP, FTP, SMTP or LDAP (OpenLDAP only) response code. This option was previously known as CURLINFO_HTTP_CODE in libcurl 7.10.7 and earlier. The stored value is zero if no server response code has been received. Note that a proxy\(aqs CONNECT response should be read with \fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. .SH PROTOCOLS This functionality affects ftp, http, ldap and smtp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long response_code; curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &response_code); } curl_easy_cleanup(curl); } } .fi .SH NOTES The former name, CURLINFO_HTTP_CODE, was added in 7.4.1. Support for SMTP responses added in 7.25.0, for OpenLDAP in 7.81.0. .SH AVAILABILITY Added in curl 7.10.8 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_HTTP_CONNECTCODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.55 KB	2025-07-08 09:41
📄 CURLINFO_RETRY_AFTER.3 .\" generated by cd2nroff 0.1 from CURLINFO_RETRY_AFTER.md .TH CURLINFO_RETRY_AFTER 3 "2025-06-27" libcurl .SH NAME CURLINFO_RETRY_AFTER \- returns the Retry\-After retry delay .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RETRY_AFTER, curl_off_t retry); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t variable to receive the number of seconds the HTTP server suggests the client should wait until the next request is issued. The information from the "Retry\-After:" header. While the HTTP header might contain a fixed date string, the \fICURLINFO_RETRY_AFTER(3)\fP always returns the number of seconds to wait \- or zero if there was no header or the header could not be parsed. This option used to return a negative wait time if the server provided a date in the past. Since 8.12.0, a negative wait time is returned as zero. In any case we recommend checking that the wait time is within an acceptable range for your circumstance. .SH DEFAULT Zero if there was no header. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { curl_off_t wait = 0; curl_easy_getinfo(curl, CURLINFO_RETRY_AFTER, &wait); if(wait) printf("Wait for %" CURL_FORMAT_CURL_OFF_T " seconds\\n", wait); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.66.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADERFUNCTION (3), .BR CURLOPT_STDERR (3), .BR curl_easy_header (3)	1.84 KB	2025-07-08 09:41
📄 CURLINFO_RTSP_CLIENT_CSEQ.3 .\" generated by cd2nroff 0.1 from CURLINFO_RTSP_CLIENT_CSEQ.md .TH CURLINFO_RTSP_CLIENT_CSEQ 3 "2025-06-27" libcurl .SH NAME CURLINFO_RTSP_CLIENT_CSEQ \- get the next RTSP client CSeq .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RTSP_CLIENT_CSEQ, long cseq); .fi .SH DESCRIPTION Pass a pointer to a long to receive the next CSeq that is expected to be used by the application. .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long cseq; curl_easy_getinfo(curl, CURLINFO_RTSP_CLIENT_CSEQ, &cseq); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_CSEQ_RECV (3), .BR CURLINFO_RTSP_SERVER_CSEQ (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.19 KB	2025-07-08 09:41
📄 CURLINFO_RTSP_CSEQ_RECV.3 .\" generated by cd2nroff 0.1 from CURLINFO_RTSP_CSEQ_RECV.md .TH CURLINFO_RTSP_CSEQ_RECV 3 "2025-06-27" libcurl .SH NAME CURLINFO_RTSP_CSEQ_RECV \- get the recently received CSeq .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RTSP_CSEQ_RECV, long cseq); .fi .SH DESCRIPTION Pass a pointer to a long to receive the most recently received CSeq from the server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you may wish to troubleshoot and/or fix the CSeq mismatch by peeking at this value. .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long cseq; curl_easy_getinfo(curl, CURLINFO_RTSP_CSEQ_RECV, &cseq); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_SERVER_CSEQ (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.26 KB	2025-07-08 09:41
📄 CURLINFO_RTSP_SERVER_CSEQ.3 .\" generated by cd2nroff 0.1 from CURLINFO_RTSP_SERVER_CSEQ.md .TH CURLINFO_RTSP_SERVER_CSEQ 3 "2025-06-27" libcurl .SH NAME CURLINFO_RTSP_SERVER_CSEQ \- get the next RTSP server CSeq .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RTSP_SERVER_CSEQ, long cseq); .fi .SH DESCRIPTION Pass a pointer to a long to receive the next CSeq that is expected to be used by the application. Listening for server initiated requests is not implemented. Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { long cseq; curl_easy_getinfo(curl, CURLINFO_RTSP_SERVER_CSEQ, &cseq); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_CSEQ_RECV (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.35 KB	2025-07-08 09:41
📄 CURLINFO_RTSP_SESSION_ID.3 .\" generated by cd2nroff 0.1 from CURLINFO_RTSP_SESSION_ID.md .TH CURLINFO_RTSP_SESSION_ID 3 "2025-06-27" libcurl .SH NAME CURLINFO_RTSP_SESSION_ID \- get RTSP session ID .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_RTSP_SESSION_ID, char id); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive a pointer to a string holding the most recent RTSP Session ID. Applications wishing to resume an RTSP session on another connection should retrieve this info before closing the active connection. The \fBid\fP pointer is NULL or points to private memory. You MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://rtsp.example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { char *id; curl_easy_getinfo(curl, CURLINFO_RTSP_SESSION_ID, &id); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_CSEQ_RECV (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.42 KB	2025-07-08 09:41
📄 CURLINFO_SCHEME.3 .\" generated by cd2nroff 0.1 from CURLINFO_SCHEME.md .TH CURLINFO_SCHEME 3 "2025-06-27" libcurl .SH NAME CURLINFO_SCHEME \- get the URL scheme (sometimes called protocol) used in the connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SCHEME, char scheme); .fi .SH DESCRIPTION Pass a pointer to a char pointer to receive the pointer to a null\-terminated string holding the URL scheme used for the most recent connection done with this CURL \fBhandle\fP. The \fBscheme\fP pointer is NULL or points to private memory. You MUST NOT free \- it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the corresponding curl handle. The returned scheme might be upper or lowercase. Do comparisons case insensitively. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res == CURLE_OK) { char scheme = NULL; curl_easy_getinfo(curl, CURLINFO_SCHEME, &scheme); if(scheme) printf("scheme: %s\\n", scheme); / scheme: HTTP */ } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_EFFECTIVE_URL (3), .BR CURLINFO_PROTOCOL (3), .BR CURLINFO_RESPONSE_CODE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.61 KB	2025-07-08 09:41
📄 CURLINFO_SIZE_DOWNLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_SIZE_DOWNLOAD.md .TH CURLINFO_SIZE_DOWNLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_SIZE_DOWNLOAD \- get the number of downloaded bytes .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SIZE_DOWNLOAD, double dlp); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total amount of bytes that were downloaded. The amount is only for the latest transfer and gets reset again for each new transfer. This counts actual payload data, what\(aqs also commonly called body. All meta and header data is excluded and not included in this number. \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request / res = curl_easy_perform(curl); if(!res) { / check the size */ double dl; res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD, &dl); if(!res) { printf("Downloaded %.0f bytes\\n", dl); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_DOWNLOAD_T (3), .BR CURLINFO_SIZE_UPLOAD_T (3), .BR CURLOPT_MAXFILESIZE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.64 KB	2025-07-08 09:41
📄 CURLINFO_SIZE_DOWNLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_SIZE_DOWNLOAD_T.md .TH CURLINFO_SIZE_DOWNLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_SIZE_DOWNLOAD_T \- get the number of downloaded bytes .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SIZE_DOWNLOAD_T, curl_off_t dlp); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that were downloaded. The amount is only for the latest transfer and gets reset again for each new transfer. This counts actual payload data, what\(aqs also commonly called body. All meta and header data is excluded from this amount. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request / res = curl_easy_perform(curl); if(!res) { / check the size */ curl_off_t dl; res = curl_easy_getinfo(curl, CURLINFO_SIZE_DOWNLOAD_T, &dl); if(!res) { printf("Downloaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", dl); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_DOWNLOAD (3), .BR CURLINFO_SIZE_UPLOAD_T (3), .BR CURLOPT_MAXFILESIZE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.56 KB	2025-07-08 09:41
📄 CURLINFO_SIZE_UPLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_SIZE_UPLOAD.md .TH CURLINFO_SIZE_UPLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_SIZE_UPLOAD \- get the number of uploaded bytes .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SIZE_UPLOAD, double uploadp); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total amount of bytes that were uploaded. \fICURLINFO_SIZE_UPLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { double ul; res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD, &ul); if(!res) { printf("Uploaded %.0f bytes\\n", ul); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_DOWNLOAD_T (3), .BR CURLINFO_SIZE_UPLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.37 KB	2025-07-08 09:41
📄 CURLINFO_SIZE_UPLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_SIZE_UPLOAD_T.md .TH CURLINFO_SIZE_UPLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_SIZE_UPLOAD_T \- get the number of uploaded bytes .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SIZE_UPLOAD_T, curl_off_t uploadp); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the total amount of bytes that were uploaded. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t ul; res = curl_easy_getinfo(curl, CURLINFO_SIZE_UPLOAD_T, &ul); if(!res) { printf("Uploaded %" CURL_FORMAT_CURL_OFF_T " bytes\\n", ul); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_DOWNLOAD_T (3), .BR CURLINFO_SIZE_UPLOAD (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.29 KB	2025-07-08 09:41
📄 CURLINFO_SPEED_DOWNLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_SPEED_DOWNLOAD.md .TH CURLINFO_SPEED_DOWNLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_SPEED_DOWNLOAD \- get download speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SPEED_DOWNLOAD, double speed); .fi .SH DESCRIPTION Pass a pointer to a double to receive the average download speed that curl measured for the complete download. Measured in bytes/second. \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { double speed; res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD, &speed); if(!res) { printf("Download speed %.0f bytes/sec\\n", speed); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_UPLOAD_T (3), .BR CURLINFO_SPEED_UPLOAD (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.44 KB	2025-07-08 09:41
📄 CURLINFO_SPEED_DOWNLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_SPEED_DOWNLOAD_T.md .TH CURLINFO_SPEED_DOWNLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_SPEED_DOWNLOAD_T \- get download speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SPEED_DOWNLOAD_T, curl_off_t speed); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the average download speed that curl measured for the complete download. Measured in bytes/second. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t speed; res = curl_easy_getinfo(curl, CURLINFO_SPEED_DOWNLOAD_T, &speed); if(!res) { printf("Download speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SIZE_UPLOAD_T (3), .BR CURLINFO_SPEED_UPLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.37 KB	2025-07-08 09:41
📄 CURLINFO_SPEED_UPLOAD.3 .\" generated by cd2nroff 0.1 from CURLINFO_SPEED_UPLOAD.md .TH CURLINFO_SPEED_UPLOAD 3 "2025-06-27" libcurl .SH NAME CURLINFO_SPEED_UPLOAD \- get upload speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SPEED_UPLOAD, double speed); .fi .SH DESCRIPTION Pass a pointer to a double to receive the average upload speed that curl measured for the complete upload. Measured in bytes/second. \fICURLINFO_SPEED_UPLOAD_T(3)\fP is a newer replacement that returns a more sensible variable type. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { double speed; res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD, &speed); if(!res) { printf("Upload speed %.0f bytes/sec\\n", speed); } } } } .fi .SH DEPRECATED Deprecated since 7.55.0. .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SPEED_DOWNLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.37 KB	2025-07-08 09:41
📄 CURLINFO_SPEED_UPLOAD_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_SPEED_UPLOAD_T.md .TH CURLINFO_SPEED_UPLOAD_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_SPEED_UPLOAD_T \- get upload speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SPEED_UPLOAD_T, curl_off_t speed); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the average upload speed that curl measured for the complete upload. Measured in bytes/second. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t speed; res = curl_easy_getinfo(curl, CURLINFO_SPEED_UPLOAD_T, &speed); if(!res) { printf("Upload speed %" CURL_FORMAT_CURL_OFF_T " bytes/sec\\n", speed); } } } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SPEED_DOWNLOAD_T (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.31 KB	2025-07-08 09:41
📄 CURLINFO_SSL_ENGINES.3 .\" generated by cd2nroff 0.1 from CURLINFO_SSL_ENGINES.md .TH CURLINFO_SSL_ENGINES 3 "2025-06-27" libcurl .SH NAME CURLINFO_SSL_ENGINES \- get an slist of OpenSSL crypto\-engines .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SSL_ENGINES, struct curl_slist engine_list); .fi .SH DESCRIPTION Pass the address of a \(aqstruct curl_slist \(aq to receive a linked\-list of OpenSSL crypto\-engines supported. Note that engines are normally implemented in separate dynamic libraries. Hence not all the returned engines may be available at runtime. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP on the list pointer once you are done with it, as libcurl does not free this data for you. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_slist engines; res = curl_easy_getinfo(curl, CURLINFO_SSL_ENGINES, &engines); if((res == CURLE_OK) && engines) { /* we have a list, free it when done using it */ curl_slist_free_all(engines); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.12.3 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLENGINE (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.59 KB	2025-07-08 09:41
📄 CURLINFO_SSL_VERIFYRESULT.3 .\" generated by cd2nroff 0.1 from CURLINFO_SSL_VERIFYRESULT.md .TH CURLINFO_SSL_VERIFYRESULT 3 "2025-06-27" libcurl .SH NAME CURLINFO_SSL_VERIFYRESULT \- get the result of the certificate verification .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_SSL_VERIFYRESULT, long result); .fi .SH DESCRIPTION Pass a pointer to a long to receive the result of the server SSL certificate verification that was requested (using the \fICURLOPT_SSL_VERIFYPEER(3)\fP option). 0 is a positive result. Non\-zero is an error. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; long verifyresult; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res) { printf("error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); return 1; } res = curl_easy_getinfo(curl, CURLINFO_SSL_VERIFYRESULT, &verifyresult); if(!res) { printf("The peer verification said %s\\n", (verifyresult ? "bad" : "fine")); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.5 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PROXY_SSL_VERIFYRESULT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.66 KB	2025-07-08 09:41
📄 CURLINFO_STARTTRANSFER_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_STARTTRANSFER_TIME.md .TH CURLINFO_STARTTRANSFER_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_STARTTRANSFER_TIME \- get the time until the first byte is received .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_STARTTRANSFER_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the time, in seconds, it took from the start until the first byte is received by libcurl. This includes \fICURLINFO_PRETRANSFER_TIME(3)\fP and also the time the server needs to calculate the result. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double start; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME, &start); if(CURLE_OK == res) { printf("Time: %.1f", start); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.2 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_STARTTRANSFER_TIME_T (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.61 KB	2025-07-08 09:41
📄 CURLINFO_STARTTRANSFER_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_STARTTRANSFER_TIME_T.md .TH CURLINFO_STARTTRANSFER_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_STARTTRANSFER_TIME_T \- get the time until the first byte is received .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_STARTTRANSFER_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the time, in microseconds, it took from the start until the first byte is received by libcurl. This includes \fICURLINFO_PRETRANSFER_TIME_T(3)\fP and also the time the server needs to calculate the result. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t start; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_STARTTRANSFER_TIME_T, &start); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", start / 1000000, (long)(start % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_STARTTRANSFER_TIME (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.72 KB	2025-07-08 09:41
📄 CURLINFO_TLS_SESSION.3 .\" generated by cd2nroff 0.1 from CURLINFO_TLS_SESSION.md .TH CURLINFO_TLS_SESSION 3 "2025-06-27" libcurl .SH NAME CURLINFO_TLS_SESSION \- get TLS session info .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_TLS_SESSION, struct curl_tlssessioninfo session); .fi .SH DESCRIPTION \fBThis option has been superseded\fP by \fICURLINFO_TLS_SSL_PTR(3)\fP which was added in 7.48.0. The only reason you would use this option instead is if you could be using a version of libcurl earlier than 7.48.0. This option is exactly the same as \fICURLINFO_TLS_SSL_PTR(3)\fP except in the case of OpenSSL. If the session \fIbackend\fP is CURLSSLBACKEND_OPENSSL the session \fIinternals\fP pointer varies depending on the option: \fICURLINFO_TLS_SESSION(3)\fP OpenSSL session \fIinternals\fP is \fBSSL_CTX \fP. \fICURLINFO_TLS_SSL_PTR(3)\fP OpenSSL session \fIinternals\fP is \fBSSL \fP. You can obtain an \fBSSL_CTX\fP pointer from an SSL pointer using OpenSSL function \fISSL_get_SSL_CTX(3)\fP. Therefore unless you need compatibility with older versions of libcurl use \fICURLINFO_TLS_SSL_PTR(3)\fP. Refer to that document for more information. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_tlssessioninfo *tls; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res) printf("error: %s\\n", curl_easy_strerror(res)); curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &tls); curl_easy_cleanup(curl); } } .fi .SH DEPRECATED Deprecated since 7.48.0 .SH AVAILABILITY Added in curl 7.34.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_TLS_SSL_PTR (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	2.1 KB	2025-07-08 09:41
📄 CURLINFO_TLS_SSL_PTR.3 .\" generated by cd2nroff 0.1 from CURLINFO_TLS_SSL_PTR.md .TH CURLINFO_TLS_SSL_PTR 3 "2025-06-27" libcurl .SH NAME CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_TLS_SSL_PTR, struct curl_tlssessioninfo session); / if you need compatibility with libcurl < 7.48.0 use CURLINFO_TLS_SESSION instead: / CURLcode curl_easy_getinfo(CURL handle, CURLINFO_TLS_SESSION, struct curl_tlssessioninfo *session); .fi .SH DESCRIPTION Pass a pointer to a \fIstruct curl_tlssessioninfo \fP. The pointer is initialized to refer to a \fIstruct curl_tlssessioninfo \fP* that contains an enum indicating the SSL library used for the handshake and a pointer to the respective internal TLS session structure of this underlying SSL library. This option may be useful for example to extract certificate information in a format convenient for further processing, such as manual validation. Refer to the \fBLIMITATIONS\fP section. .nf struct curl_tlssessioninfo { curl_sslbackend backend; void internals; }; .fi The \fIbackend\fP struct member is one of these defines: CURLSSLBACKEND_NONE (when built without TLS support), CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_SECURETRANSPORT, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL or CURLSSLBACKEND_SCHANNEL. (Note that the OpenSSL forks are all reported as just OpenSSL here.) The \fIinternals\fP struct member points to a TLS library specific pointer for the active ("in use") SSL connection, with the following underlying types: .IP GnuTLS \fBgnutls_session_t\fP .IP OpenSSL \fICURLINFO_TLS_SESSION(3)\fP: \fBSSL_CTX \fP \fICURLINFO_TLS_SSL_PTR(3)\fP: \fBSSL \fP* Since 7.48.0 the \fIinternals\fP member can point to these other SSL backends as well: .IP mbedTLS \fBmbedTLS_ssl_context \fP* .IP "Secure Channel" \fBCtxtHandle \fP* .IP "Secure Transport" \fBSSLContext \fP* .IP wolfSSL \fBSSL \fP* .PP If the \fIinternals\fP pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established or the connection is no longer associated with the easy handle (e.g. \fIcurl_easy_perform(3)\fP has returned). .SH LIMITATIONS This option has some limitations that could make it unsafe when it comes to the manual verification of certificates. This option only retrieves the first in\-use SSL session pointer for your easy handle, however your easy handle may have more than one in\-use SSL session if using FTP over SSL. That is because the FTP protocol has a control channel and a data channel and one or both may be over SSL. Currently there is no way to retrieve a second in\-use SSL session associated with an easy handle. This option has not been thoroughly tested with clear text protocols that can be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with \fICURLOPT_USE_SSL(3)\fP. Though you can to retrieve the SSL pointer, it is possible that before you can do that, data (including auth) may have already been sent over a connection after it was upgraded. Renegotiation. If unsafe renegotiation or renegotiation in a way that the certificate is allowed to change is allowed by your SSL library this may occur and the certificate may change, and data may continue to be sent or received after renegotiation but before you are able to get the (possibly) changed SSL pointer, with the (possibly) changed certificate information. Instead of using this option to poll for certificate changes use \fICURLOPT_SSL_CTX_FUNCTION(3)\fP to set a verification callback, if supported. That is safer and does not suffer from any of the problems above. How are you using this option? Are you affected by any of these limitations? Please let us know by making a comment at https://github.com/curl/curl/issues/685 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf #include <curl/curl.h> #include <openssl/ssl.h> CURL curl; static size_t wf(void ptr, size_t size, size_t nmemb, void stream) { const struct curl_tlssessioninfo info = NULL; CURLcode res = curl_easy_getinfo(curl, CURLINFO_TLS_SSL_PTR, &info); if(info && !res) { if(CURLSSLBACKEND_OPENSSL == info->backend) { printf("OpenSSL ver. %s\\n", SSL_get_version((SSL)info->internals)); } } return size nmemb; } int main(int argc, char **argv) { CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wf); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } return res; } .fi .SH HISTORY This option supersedes \fICURLINFO_TLS_SESSION(3)\fP which was added in 7.34.0. This option is exactly the same as that option except in the case of OpenSSL. .SH AVAILABILITY Added in curl 7.48.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_TLS_SESSION (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	5.27 KB	2025-07-08 09:41
📄 CURLINFO_TOTAL_TIME.3 .\" generated by cd2nroff 0.1 from CURLINFO_TOTAL_TIME.md .TH CURLINFO_TOTAL_TIME 3 "2025-06-27" libcurl .SH NAME CURLINFO_TOTAL_TIME \- get total time of previous transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_TOTAL_TIME, double timep); .fi .SH DESCRIPTION Pass a pointer to a double to receive the total time in seconds for the previous transfer, including name resolving, TCP connect etc. The double represents the time in seconds, including fractions. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; double total; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME, &total); if(CURLE_OK == res) { printf("Time: %.1f", total); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_TOTAL_TIME_T (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.49 KB	2025-07-08 09:41
📄 CURLINFO_TOTAL_TIME_T.3 .\" generated by cd2nroff 0.1 from CURLINFO_TOTAL_TIME_T.md .TH CURLINFO_TOTAL_TIME_T 3 "2025-06-27" libcurl .SH NAME CURLINFO_TOTAL_TIME_T \- get total time of previous transfer in microseconds .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_TOTAL_TIME_T, curl_off_t timep); .fi .SH DESCRIPTION Pass a pointer to a curl_off_t to receive the total time in microseconds for the previous transfer, including name resolving, TCP connect etc. The curl_off_t represents the time in microseconds. When a redirect is followed, the time from each request is added together. See also the TIMES overview in the \fIcurl_easy_getinfo(3)\fP man page. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_off_t total; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(CURLE_OK == res) { res = curl_easy_getinfo(curl, CURLINFO_TOTAL_TIME_T, &total); if(CURLE_OK == res) { printf("Time: %" CURL_FORMAT_CURL_OFF_T ".%06ld", total / 1000000, (long)(total % 1000000)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_TOTAL_TIME (3), .BR CURLOPT_TIMEOUT (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.62 KB	2025-07-08 09:41
📄 CURLINFO_USED_PROXY.3 .\" generated by cd2nroff 0.1 from CURLINFO_USED_PROXY.md .TH CURLINFO_USED_PROXY 3 "2025-06-27" libcurl .SH NAME CURLINFO_USED_PROXY \- whether the transfer used a proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_USED_PROXY, long authp); .fi .SH DESCRIPTION Pass a pointer to a long. It gets set to zero set if no proxy was used in the previous transfer or a non\-zero value if a proxy was used. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(int argc, char argv[]) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, argv[1]); curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); curl_easy_setopt(curl, CURLOPT_NOPROXY, "example.com"); res = curl_easy_perform(curl); if(!res) { /* extract the available proxy authentication types */ long used; res = curl_easy_getinfo(curl, CURLINFO_USED_PROXY, &used); if(!res) { printf("The proxy was %sused\\n", used ? "": "NOT "); } } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.7.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NOPROXY (3), .BR CURLOPT_PROXY (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.47 KB	2025-07-08 09:41
📄 CURLINFO_XFER_ID.3 .\" generated by cd2nroff 0.1 from CURLINFO_XFER_ID.md .TH CURLINFO_XFER_ID 3 "2025-06-27" libcurl .SH NAME CURLINFO_XFER_ID \- get the ID of a transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL handle, CURLINFO_XFER_ID, curl_off_t xfer_id); .fi .SH DESCRIPTION Pass a pointer to a \fIcurl_off_t\fP to receive the identifier of the current/last transfer done with the handle. Stores \-1 if no transfer has been started yet for the handle. The transfer id is unique among all transfers performed using the same connection cache. This is implicitly the case for all transfers in the same multi handle. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Perform the request */ res = curl_easy_perform(curl); if(!res) { curl_off_t xfer_id; res = curl_easy_getinfo(curl, CURLINFO_XFER_ID, &xfer_id); if(!res) { printf("Transfer ID: %" CURL_FORMAT_CURL_OFF_T "\\n", xfer_id); } } } } .fi .SH AVAILABILITY Added in curl 8.2.0 .SH RETURN VALUE \fIcurl_easy_getinfo(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONN_ID (3), .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3)	1.46 KB	2025-07-08 09:41
📄 CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 .\" generated by cd2nroff 0.1 from CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.md .TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "2025-06-27" libcurl .SH NAME CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \- chunk length threshold for pipelining .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, long size); .fi .SH DESCRIPTION No function since pipelining was removed in 7.62.0. Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is currently processing a chunked (Transfer\-encoding: chunked) request with a current chunk length larger than \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered for additional requests, even if it is shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .SH DEFAULT 0, which means that penalization is inactive. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); long maxchunk = 10000; curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), .BR CURLMOPT_MAX_PIPELINE_LENGTH (3), .BR CURLMOPT_PIPELINING (3)	1.4 KB	2025-07-08 09:41
📄 CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 .\" generated by cd2nroff 0.1 from CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.md .TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "2025-06-27" libcurl .SH NAME CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \- size threshold for pipelining penalty .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, long size); .fi .SH DESCRIPTION No function since pipelining was removed in 7.62.0. Pass a long with a \fBsize\fP in bytes. If a transfer in a pipeline is currently processing a request with a Content\-Length larger than this \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP, that pipeline is not considered for additional requests, even if it is shorter than \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .SH DEFAULT 0, which means that the size penalization is inactive. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); long maxlength = 10000; curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3), .BR CURLMOPT_PIPELINING (3)	1.35 KB	2025-07-08 09:41
📄 CURLMOPT_MAXCONNECTS.3 .\" generated by cd2nroff 0.1 from CURLMOPT_MAXCONNECTS.md .TH CURLMOPT_MAXCONNECTS 3 "2025-06-27" libcurl .SH NAME CURLMOPT_MAXCONNECTS \- size of connection cache .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_MAXCONNECTS, long max); .fi .SH DESCRIPTION Pass a long indicating the \fBmax\fP, the maximum amount of connections that libcurl may keep alive in its connection cache after use. By default libcurl enlarges the size for each added easy handle to make it fit 4 times the number of added easy handles. By setting this option, you prevent the cache size from growing beyond the limit set by you. When the cache is full, curl closes the oldest connection present in the cache to prevent the number of connections from increasing. This option is for the multi handle\(aqs use only, when using the easy interface you should instead use the \fICURLOPT_MAXCONNECTS(3)\fP option. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP for limiting the number of active connections. Changing this value when there are transfers in progress is possible, and the new value is then used the next time checks are performed. Lowering the value does not close down any active transfers, it simply does not allow new ones to get made. .SH DEFAULT See DESCRIPTION .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* only keep 10 connections in the cache */ curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L); } .fi .SH AVAILABILITY Added in curl 7.16.3 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAX_HOST_CONNECTIONS (3), .BR CURLOPT_MAXCONNECTS (3)	1.8 KB	2025-07-08 09:41
📄 CURLMOPT_MAX_CONCURRENT_STREAMS.3 .\" generated by cd2nroff 0.1 from CURLMOPT_MAX_CONCURRENT_STREAMS.md .TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "2025-06-27" libcurl .SH NAME CURLMOPT_MAX_CONCURRENT_STREAMS \- max concurrent streams for http2 .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_MAX_CONCURRENT_STREAMS, long max); .fi .SH DESCRIPTION Pass a long indicating the \fBmax\fP. The set number is used as the maximum number of concurrent streams libcurl should support on connections done using HTTP/2 or HTTP/3. Valid values range from 1 to 2147483647 (2^31 \- 1) and defaults to 100. The value passed here would be honored based on other system resources properties. .SH DEFAULT 100 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* max concurrent streams 200 */ curl_multi_setopt(m, CURLMOPT_MAX_CONCURRENT_STREAMS, 200L); } .fi .SH AVAILABILITY Added in curl 7.67.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAXCONNECTS (3), .BR CURLOPT_MAXCONNECTS (3)	1.22 KB	2025-07-08 09:41
📄 CURLMOPT_MAX_HOST_CONNECTIONS.3 .\" generated by cd2nroff 0.1 from CURLMOPT_MAX_HOST_CONNECTIONS.md .TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "2025-06-27" libcurl .SH NAME CURLMOPT_MAX_HOST_CONNECTIONS \- max number of connections to a single host .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_MAX_HOST_CONNECTIONS, long max); .fi .SH DESCRIPTION Pass a long to indicate \fBmax\fP, the maximum amount of simultaneously open connections libcurl may hold a single host (a host being the same as a hostname + port number pair). For each new transfer to the same host, libcurl might open a new connection up to the limit set by \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. When the limit is reached, new sessions are kept pending until a connection becomes available. The default \fBmax\fP value is 0, unlimited. This set limit is also used for proxy connections, and then the proxy is considered to be the host for which this limit counts. When more transfers are added to the multi handle than what can be performed due to the set limit, they are queued up waiting for their chance. While a transfer is queued up internally waiting for a connection, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the waiting time, meaning that if you set a too narrow timeout the transfer might never even start before it times out. The \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP time is also similarly still treated as a per\-connect timeout and might expire even before making a new connection is permitted. Changing this value while there are transfers in progress is possible. The new value is then used the next time checks are performed. Lowering the value does not close down any active transfers, it simply does not allow new ones to get made. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* do no more than 2 connections per host */ curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAXCONNECTS (3), .BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3)	2.3 KB	2025-07-08 09:41
📄 CURLMOPT_MAX_PIPELINE_LENGTH.3 .\" generated by cd2nroff 0.1 from CURLMOPT_MAX_PIPELINE_LENGTH.md .TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "2025-06-27" libcurl .SH NAME CURLMOPT_MAX_PIPELINE_LENGTH \- maximum number of requests in a pipeline .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_MAX_PIPELINE_LENGTH, long max); .fi .SH DESCRIPTION No function since pipelining was removed in 7.62.0. Pass a long. The set \fBmax\fP number is used as the maximum amount of outstanding requests in an HTTP/1.1 pipeline. This option is only used for HTTP/1.1 pipelining, not for HTTP/2 multiplexing. When this limit is reached, libcurl creates another connection to the same host (see \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP), or queue the request until one .nf of the pipelines to the host is ready to accept a request. Thus, the total .fi \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .SH DEFAULT 5 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* set a more conservative pipe length */ curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAX_HOST_CONNECTIONS (3), .BR CURLMOPT_PIPELINING (3)	1.44 KB	2025-07-08 09:41
📄 CURLMOPT_MAX_TOTAL_CONNECTIONS.3 .\" generated by cd2nroff 0.1 from CURLMOPT_MAX_TOTAL_CONNECTIONS.md .TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "2025-06-27" libcurl .SH NAME CURLMOPT_MAX_TOTAL_CONNECTIONS \- max simultaneously open connections .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_MAX_TOTAL_CONNECTIONS, long amount); .fi .SH DESCRIPTION Pass a long for the \fBamount\fP. The set number is used as the maximum number of simultaneously open connections in total using this multi handle. For each new session, libcurl might open a new connection up to the limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl can try multiplexing if the host is capable of it. When more transfers are added to the multi handle than what can be performed due to the set limit, they get queued up waiting for their chance. While a transfer is queued up internally waiting for a connection, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout is counted inclusive of the waiting time, meaning that if you set a too narrow timeout the transfer might never even start before it times out. The \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP time is also similarly still treated as a per\-connect timeout and might expire even before making a new connection is permitted. Changing this value while there are transfers in progress is possible. The new value is then used the next time checks are performed. Lowering the value does not close down any active transfers, it simply does not allow new ones to get made. .SH DEFAULT 0, which means that there is no limit. It is then simply controlled by the number of easy handles added concurrently and how much multiplexing is being done. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* never do more than 15 connections */ curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAXCONNECTS (3), .BR CURLMOPT_MAX_HOST_CONNECTIONS (3)	2.24 KB	2025-07-08 09:41
📄 CURLMOPT_PIPELINING.3 .\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING.md .TH CURLMOPT_PIPELINING 3 "2025-06-27" libcurl .SH NAME CURLMOPT_PIPELINING \- enable HTTP multiplexing .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_PIPELINING, long bitmask); .fi .SH DESCRIPTION Pass in the correct value in the \fBbitmask\fP parameter to instruct libcurl to enable multiplexing for this multi handle. With multiplexing enabled, libcurl attempts to do multiple transfers over the same connection when doing parallel transfers to the same hosts. .IP "CURLPIPE_NOTHING (0)" Make no attempts at multiplexing. .IP "CURLPIPE_HTTP1 (1)" This bit is deprecated and has no effect since version 7.62.0. .IP "CURLPIPE_MULTIPLEX (2)" If this bit is set, libcurl tries to multiplex the new transfer over an existing connection if possible. This requires HTTP/2 or HTTP/3. .SH DEFAULT \fBCURLPIPE_MULTIPLEX\fP .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURLM m = curl_multi_init(); /* try HTTP/2 multiplexing */ curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_MULTIPLEX); } .fi .SH HISTORY The multiplex support bit was added in 7.43.0. HTTP/1 Pipelining support was disabled in 7.62.0. Since 7.62.0, \fBCURLPIPE_MULTIPLEX\fP is enabled by default. Before that, default was \fBCURLPIPE_NOTHING\fP. .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE (3), .BR CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE (3), .BR CURLMOPT_MAXCONNECTS (3), .BR CURLMOPT_MAX_HOST_CONNECTIONS (3), .BR CURLMOPT_MAX_PIPELINE_LENGTH (3), .BR CURLMOPT_PIPELINING_SITE_BL (3)	1.8 KB	2025-07-08 09:41
📄 CURLMOPT_PIPELINING_SERVER_BL.3 .\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING_SERVER_BL.md .TH CURLMOPT_PIPELINING_SERVER_BL 3 "2025-06-27" libcurl .SH NAME CURLMOPT_PIPELINING_SERVER_BL \- pipelining server block list .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_PIPELINING_SERVER_BL, char servers); .fi .SH DESCRIPTION No function since pipelining was removed in 7.62.0. Pass a \fBservers\fP array of char , ending with a NULL entry. This is a list of server types prefixes (in the Server: HTTP header) that are blocked from pipelining, i.e server types that are known to not support HTTP pipelining. The array is copied by libcurl. Note that the comparison matches if the Server: header begins with the string in the block list, i.e "Server: Ninja 1.2.3" and "Server: Ninja 1.4.0" can both be blocked by having "Ninja" in the list. Pass a NULL pointer to clear the block list. .SH DEFAULT NULL, which means that there is no block list. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf static char server_block_list[] = { "Microsoft-IIS/6.0", "nginx/0.8.54", NULL }; int main(void) { CURLM m = curl_multi_init(); curl_multi_setopt(m, CURLMOPT_PIPELINING_SERVER_BL, server_block_list); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLMOPT_PIPELINING_SITE_BL (3)	1.56 KB	2025-07-08 09:41
📄 CURLMOPT_PIPELINING_SITE_BL.3 .\" generated by cd2nroff 0.1 from CURLMOPT_PIPELINING_SITE_BL.md .TH CURLMOPT_PIPELINING_SITE_BL 3 "2025-06-27" libcurl .SH NAME CURLMOPT_PIPELINING_SITE_BL \- pipelining host block list .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_PIPELINING_SITE_BL, char hosts); .fi .SH DESCRIPTION No function since pipelining was removed in 7.62.0. Pass a \fBhosts\fP array of char , ending with a NULL entry. This is a list of sites that are blocked from pipelining, i.e sites that are known to not support HTTP pipelining. The array is copied by libcurl. Pass a NULL pointer to clear the block list. .SH DEFAULT NULL, which means that there is no block list. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf static char site_block_list[] = { "www.haxx.se", "www.example.com:1234", NULL }; int main(void) { CURLM m = curl_multi_init(); curl_multi_setopt(m, CURLMOPT_PIPELINING_SITE_BL, site_block_list); } .fi .SH AVAILABILITY Added in curl 7.30.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLMOPT_PIPELINING_SERVER_BL (3)	1.3 KB	2025-07-08 09:41
📄 CURLMOPT_PUSHDATA.3 .\" generated by cd2nroff 0.1 from CURLMOPT_PUSHDATA.md .TH CURLMOPT_PUSHDATA 3 "2025-06-27" libcurl .SH NAME CURLMOPT_PUSHDATA \- pointer to pass to push callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_PUSHDATA, void pointer); .fi .SH DESCRIPTION Set a \fIpointer\fP to pass as the last argument to the \fICURLMOPT_PUSHFUNCTION(3)\fP callback. The pointer is not touched or used by libcurl itself, only passed on to the callback function. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf #include <string.h> /* only allow pushes for filenames starting with "push-" / int push_callback(CURL parent, CURL easy, size_t num_headers, struct curl_pushheaders headers, void clientp) { char headp; int transfers = (int )clientp; FILE out; headp = curl_pushheader_byname(headers, ":path"); if(headp && !strncmp(headp, "/push-", 6)) { fprintf(stderr, "The PATH is %s\\n", headp); / save the push here / out = fopen("pushed-stream", "wb"); / write to this file / curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); (transfers)++; /* one more / return CURL_PUSH_OK; } return CURL_PUSH_DENY; } int main(void) { int counter; CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); } .fi .SH AVAILABILITY Added in curl 7.44.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLMOPT_PUSHFUNCTION (3), .BR CURLOPT_PIPEWAIT (3), .BR RFC 7540	1.8 KB	2025-07-08 09:41
📄 CURLMOPT_PUSHFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLMOPT_PUSHFUNCTION.md .TH CURLMOPT_PUSHFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes .SH SYNOPSIS .nf #include <curl/curl.h> int curl_push_callback(CURL parent, CURL easy, size_t num_headers, struct curl_pushheaders headers, void clientp); CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_PUSHFUNCTION, curl_push_callback func); .fi .SH DESCRIPTION This callback gets called when a new HTTP/2 stream is being pushed by the server (using the PUSH_PROMISE frame). If no push callback is set, all offered pushes are denied automatically. .SH CALLBACK DESCRIPTION The callback gets its arguments like this: \fIparent\fP is the handle of the stream on which this push arrives. The new handle has been duplicated from the parent, meaning that it has gotten all its options inherited. It is then up to the application to alter any options if desired. \fIeasy\fP is a newly created handle that represents this upcoming transfer. \fInum_headers\fP is the number of name+value pairs that was received and can be accessed \fIheaders\fP is a handle used to access push headers using the accessor functions described below. This only accesses and provides the PUSH_PROMISE headers, the normal response headers are provided in the header callback as usual. \fIclientp\fP is the pointer set with \fICURLMOPT_PUSHDATA(3)\fP If the callback returns CURL_PUSH_OK, the new easy handle is added to the multi handle, the callback must not do that by itself. The callback can access PUSH_PROMISE headers with two accessor functions. These functions can only be used from within this callback and they can only access the PUSH_PROMISE headers: \fIcurl_pushheader_byname(3)\fP and \fIcurl_pushheader_bynum(3)\fP. The normal response headers are passed to the header callback for pushed streams just as for normal streams. The header fields can also be accessed with \fIcurl_easy_header(3)\fP, introduced in later libcurl versions. .SH CALLBACK RETURN VALUE .IP "CURL_PUSH_OK (0)" The application has accepted the stream and it can now start receiving data, the ownership of the curl handle has been taken over by the application. .IP "CURL_PUSH_DENY (1)" The callback denies the stream and no data reaches the application, the easy handle is destroyed by libcurl. .IP "CURL_PUSH_ERROROUT (2)" Returning this code rejects the pushed stream and returns an error back on the parent stream making it get closed with an error. (Added in 7.72.0) .IP All other return codes are reserved for future use. .SH DEFAULT NULL, no callback .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf #include <string.h> /* only allow pushes for filenames starting with "push-" / int push_callback(CURL parent, CURL easy, size_t num_headers, struct curl_pushheaders headers, void clientp) { char headp; int transfers = (int )clientp; FILE out; headp = curl_pushheader_byname(headers, ":path"); if(headp && !strncmp(headp, "/push-", 6)) { fprintf(stderr, "The PATH is %s\\n", headp); / save the push here / out = fopen("pushed-stream", "wb"); / write to this file / curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); (transfers)++; /* one more / return CURL_PUSH_OK; } return CURL_PUSH_DENY; } int main(void) { int counter; CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback); curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); } .fi .SH AVAILABILITY Added in curl 7.44.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLMOPT_PUSHDATA (3), .BR CURLOPT_PIPEWAIT (3), .BR RFC 7540	3.98 KB	2025-07-08 09:41
📄 CURLMOPT_SOCKETDATA.3 .\" generated by cd2nroff 0.1 from CURLMOPT_SOCKETDATA.md .TH CURLMOPT_SOCKETDATA 3 "2025-06-27" libcurl .SH NAME CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_SOCKETDATA, void pointer); .fi .SH DESCRIPTION A data \fIpointer\fP to pass to the socket callback set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option. This pointer is not touched by libcurl but is only passed in as the socket callback\(aqs \fBclientp\fP argument. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void ours; }; static int sock_cb(CURL e, curl_socket_t s, int what, void cbp, void sockp) { struct priv p = sockp; printf("my ptr: %p\\n", p->ours); if(what == CURL_POLL_REMOVE) { / remove the socket from our collection / } if(what & CURL_POLL_IN) { / wait for read on this socket / } if(what & CURL_POLL_OUT) { / wait for write on this socket / } return 0; } int main(void) { struct priv setup; CURLM multi = curl_multi_init(); /* ... use socket callback and custom pointer */ curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE Returns CURLM_OK. .SH SEE ALSO .BR CURLMOPT_SOCKETFUNCTION (3), .BR CURLMOPT_TIMERFUNCTION (3), .BR curl_multi_socket_action (3)	1.46 KB	2025-07-08 09:41
📄 CURLMOPT_SOCKETFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLMOPT_SOCKETFUNCTION.md .TH CURLMOPT_SOCKETFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for .SH SYNOPSIS .nf #include <curl/curl.h> int socket_callback(CURL easy, / easy handle / curl_socket_t s, / socket / int what, / describes the socket / void clientp, /* private callback pointer / void socketp); /* private socket pointer / CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_SOCKETFUNCTION, socket_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. When the \fIcurl_multi_socket_action(3)\fP function is called, it uses this callback to inform the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the \fBsocket_callback\fP. The callback function gets status updates with changes since the previous time the callback was called. If the given callback pointer is set to NULL, no callback is called. libcurl then expects the application to monitor the sockets for the specific activities and tell libcurl again when something happens on one of them. Tell libcurl by calling \fIcurl_multi_socket_action(3)\fP. This callback may get invoked at any time when interacting with libcurl. This may even happen after all transfers are done and is \fIlikely\fP to happen \fIduring\fP a call to \fIcurl_multi_cleanup(3)\fP when cached connections are shut down. .SH CALLBACK ARGUMENTS \fIeasy\fP identifies the specific transfer for which this update is related. Since this callback manages a whole multi handle, an application should not make assumptions about which particular handle that is passed here. It might even be an internal easy handle that the application did not add itself. \fIs\fP is the specific socket this function invocation concerns. If the \fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about what activity on this socket the application is supposed to monitor. Subsequent calls to this callback might update the \fBwhat\fP bits for a socket that is already monitored. The socket callback should return 0 on success, and \-1 on error. If this callback returns error, \fBall\fP transfers currently in progress in this multi handle are aborted and made to fail. \fBclientp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. \fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or NULL. The \fBwhat\fP parameter informs the callback on the status of the given socket. It can hold one of these values: .IP CURL_POLL_IN Wait for incoming data. For the socket to become readable. .IP CURL_POLL_OUT Wait for outgoing data. For the socket to become writable. .IP CURL_POLL_INOUT Wait for incoming and outgoing data. For the socket to become readable or writable. .IP CURL_POLL_REMOVE The specified socket/file descriptor is no longer used by libcurl for any active transfer. It might soon be added again. .SH DEFAULT NULL (no callback) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void ours; }; static int sock_cb(CURL e, curl_socket_t s, int what, void cbp, void sockp) { struct priv p = sockp; printf("our ptr: %p\\n", p->ours); if(what == CURL_POLL_REMOVE) { / remove the socket from our collection / } if(what & CURL_POLL_IN) { / wait for read on this socket / } if(what & CURL_POLL_OUT) { / wait for write on this socket / } return 0; } int main(void) { struct priv setup; CURLM multi = curl_multi_init(); /* ... use socket callback and custom pointer */ curl_multi_setopt(multi, CURLMOPT_SOCKETFUNCTION, sock_cb); curl_multi_setopt(multi, CURLMOPT_SOCKETDATA, &setup); } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE Returns CURLM_OK. .SH SEE ALSO .BR CURLMOPT_SOCKETDATA (3), .BR CURLMOPT_TIMERFUNCTION (3), .BR curl_multi_socket_action (3)	3.94 KB	2025-07-08 09:41
📄 CURLMOPT_TIMERDATA.3 .\" generated by cd2nroff 0.1 from CURLMOPT_TIMERDATA.md .TH CURLMOPT_TIMERDATA 3 "2025-06-27" libcurl .SH NAME CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_TIMERDATA, void pointer); .fi .SH DESCRIPTION A data \fBpointer\fP to pass to the timer callback set with the \fICURLMOPT_TIMERFUNCTION(3)\fP option. This pointer is not touched by libcurl but is only be passed in to the timer callback\(aqs \fBclientp\fP argument. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int timerfunc(CURLM multi, long timeout_ms, void clientp) { struct priv mydata = clientp; printf("our ptr: %p\\n", mydata->custom); if(timeout_ms >= 0) { /* this is the new single timeout to wait for / } else { / delete the timeout, nothing to wait for now / } return 0; } int main(void) { struct priv mydata; CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); } .fi .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_SOCKETFUNCTION (3), .BR CURLMOPT_TIMERFUNCTION (3)	1.46 KB	2025-07-08 09:41
📄 CURLMOPT_TIMERFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLMOPT_TIMERFUNCTION.md .TH CURLMOPT_TIMERFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLMOPT_TIMERFUNCTION \- callback to receive timeout values .SH SYNOPSIS .nf #include <curl/curl.h> int timer_callback(CURLM multi, / multi handle / long timeout_ms, / timeout in number of ms / void clientp); /* private callback pointer / CURLMcode curl_multi_setopt(CURLM handle, CURLMOPT_TIMERFUNCTION, timer_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. Certain features, such as timeouts and retries, require you to call libcurl even when there is no activity on the file descriptors. Your callback function \fBtimer_callback\fP should install a single non\-repeating timer with an expire time of \fBtimeout_ms\fP milliseconds. When that timer fires, call either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP, depending on which interface you use. If this callback is called when a timer is already running, this new expire time \fIreplaces\fP the former timeout. The application should then effectively cancel the old timeout and set a new timeout using this new expire time. A \fBtimeout_ms\fP value of \-1 passed to this callback means you should delete the timer. All other values are valid expire times in number of milliseconds \- including zero milliseconds. The \fBtimer_callback\fP is called when the timeout expire time is changed. The \fBclientp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. The timer callback should return 0 on success, and \-1 on error. If this callback returns error, \fBall\fP transfers currently in progress in this multi handle are aborted and made to fail. This callback can be used instead of, or in addition to, \fIcurl_multi_timeout(3)\fP. \fBWARNING:\fP do not call libcurl directly from within the callback itself when the \fBtimeout_ms\fP value is zero, since it risks triggering an unpleasant recursive behavior that immediately calls another call to the callback with a zero timeout... .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int timerfunc(CURLM multi, long timeout_ms, void clientp) { struct priv mydata = clientp; printf("our ptr: %p\\n", mydata->custom); if(timeout_ms >= 0) { /* this is the new single timeout to wait for, including zero / } else { / delete the timeout, nothing to wait for now / } return 0; } int main(void) { struct priv mydata; CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc); curl_multi_setopt(multi, CURLMOPT_TIMERDATA, &mydata); } .fi .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE \fIcurl_multi_setopt(3)\fP returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_SOCKETFUNCTION (3), .BR CURLMOPT_TIMERDATA (3)	3.01 KB	2025-07-08 09:41
📄 CURLOPT_ABSTRACT_UNIX_SOCKET.3 .\" generated by cd2nroff 0.1 from CURLOPT_ABSTRACT_UNIX_SOCKET.md .TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "2025-06-27" libcurl .SH NAME CURLOPT_ABSTRACT_UNIX_SOCKET \- abstract Unix domain socket .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ABSTRACT_UNIX_SOCKET, char path); .fi .SH DESCRIPTION Enables the use of an abstract Unix domain socket instead of establishing a TCP connection to a host. The parameter should be a char * to a null\-terminated string holding the path of the socket. The path is set to \fIpath\fP prefixed by a NULL byte. This is the convention for abstract sockets, however it should be stressed that the path passed to this function should not contain a leading NULL byte. On non\-supporting platforms, the abstract address is interpreted as an empty string and fails gracefully, generating a runtime error. This option shares the same semantics as \fICURLOPT_UNIX_SOCKET_PATH(3)\fP in which documentation more details can be found. Internally, these two options share the same storage and therefore only one of them can be set per handle. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.53.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_UNIX_SOCKET_PATH (3), .BR unix (7)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_ACCEPTTIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_ACCEPTTIMEOUT_MS.md .TH CURLOPT_ACCEPTTIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_ACCEPTTIMEOUT_MS \- timeout waiting for FTP server to connect back .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ACCEPTTIMEOUT_MS, long ms); .fi .SH DESCRIPTION Pass a long telling libcurl the maximum number of milliseconds to wait for a server to connect back to libcurl when an active FTP connection is used. .SH DEFAULT 60000 milliseconds .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/path/file"); /* wait no more than 5 seconds for FTP server responses */ curl_easy_setopt(curl, CURLOPT_ACCEPTTIMEOUT_MS, 5000L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.24.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT_MS (3), .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3)	1.19 KB	2025-07-08 09:41
📄 CURLOPT_ACCEPT_ENCODING.3 .\" generated by cd2nroff 0.1 from CURLOPT_ACCEPT_ENCODING.md .TH CURLOPT_ACCEPT_ENCODING 3 "2025-06-27" libcurl .SH NAME CURLOPT_ACCEPT_ENCODING \- automatic decompression of HTTP downloads .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ACCEPT_ENCODING, char enc); .fi .SH DESCRIPTION Pass a char pointer argument specifying what encoding you would like. Sets the contents of the Accept\-Encoding: header sent in an HTTP request, and enables decoding of a response when a Content\-Encoding: header is received. libcurl potentially supports several different compressed encodings depending on what support that has been built\-in. To aid applications not having to bother about what specific algorithms this particular libcurl build supports, libcurl allows a zero\-length string to be set ("") to ask for an Accept\-Encoding: header to be used that contains all built\-in supported encodings. Alternatively, you can specify exactly the encoding or list of encodings you want in the response. The following encodings are supported: \fIidentity\fP, meaning non\-compressed, \fIdeflate\fP which requests the server to compress its response using the zlib algorithm, \fIgzip\fP which requests the gzip algorithm, (since curl 7.57.0) \fIbr\fP which is brotli and (since curl 7.72.0) \fIzstd\fP which is zstd. Provide them in the string as a comma\-separated list of accepted encodings, like: \fB"br, gzip, deflate"\fP. Set \fICURLOPT_ACCEPT_ENCODING(3)\fP to NULL to explicitly disable it, which makes libcurl not send an Accept\-Encoding: header and not decompress received contents automatically. You can also opt to just include the Accept\-Encoding: header in your request with \fICURLOPT_HTTPHEADER(3)\fP but then there is no automatic decompressing when receiving data. This is a request, not an order; the server may or may not do it. This option must be set (to any non\-NULL value) or else any unsolicited encoding done by the server is ignored. Servers might respond with Content\-Encoding even without getting a Accept\-Encoding: in the request. Servers might respond with a different Content\-Encoding than what was asked for in the request. The Content\-Length: servers send for a compressed response is supposed to indicate the length of the compressed content so when auto decoding is enabled it may not match the sum of bytes reported by the write callbacks (although, sending the length of the non\-compressed content is a common server mistake). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. .SH HISTORY This option was called CURLOPT_ENCODING before 7.21.6 .SH NOTES The specific libcurl you are using must have been built with zlib to be able to decompress gzip and deflate responses, with the brotli library to decompress brotli responses and with the zstd library to decompress zstd responses. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / enable all supported built-in compressions / curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, ""); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_HTTP_CONTENT_DECODING (3), .BR CURLOPT_TRANSFER_ENCODING (3)	3.64 KB	2025-07-08 09:41
📄 CURLOPT_ADDRESS_SCOPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_ADDRESS_SCOPE.md .TH CURLOPT_ADDRESS_SCOPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_ADDRESS_SCOPE \- scope id for IPv6 addresses .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ADDRESS_SCOPE, long scope); .fi .SH DESCRIPTION Pass a long specifying the scope id value to use when connecting to IPv6 addresses. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <net/if.h> / for if_nametoindex() / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; long my_scope_id; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); my_scope_id = if_nametoindex("eth0"); curl_easy_setopt(curl, CURLOPT_ADDRESS_SCOPE, my_scope_id); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. Returns CURLE_BAD_FUNCTION_ARGUMENT if set to a negative value. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3)	1.22 KB	2025-07-08 09:41
📄 CURLOPT_ALTSVC.3 .\" generated by cd2nroff 0.1 from CURLOPT_ALTSVC.md .TH CURLOPT_ALTSVC 3 "2025-06-27" libcurl .SH NAME CURLOPT_ALTSVC \- alt\-svc cache filename .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ALTSVC, char filename); .fi .SH DESCRIPTION Pass in a pointer to a \fIfilename\fP to instruct libcurl to use that file as the Alt\-Svc cache to read existing cache contents from and possibly also write it back to after a transfer, unless \fBCURLALTSVC_READONLYFILE\fP is set in \fICURLOPT_ALTSVC_CTRL(3)\fP. Specify a blank filename ("") to make libcurl not load from a file at all. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH SECURITY CONCERNS libcurl cannot fully protect against attacks where an attacker has write access to the same directory where it is directed to save files. This is particularly sensitive if you save files using elevated privileges. .SH DEFAULT NULL. The alt\-svc cache is not read nor written to file. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1); curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); curl_easy_perform(curl); } } .fi .SH FILE FORMAT A text based file with one line per alt\-svc entry and each line consists of nine space\-separated fields. An example line could look like .nf h2 www.example.com 8443 h3 second.example.com 443 "20190808 06:18:37" 1 0 .fi The fields of that line are: .IP h2 ALPN id for the source origin .IP www.example.comp Hostname for the source origin .IP 8443 Port number for the source origin .IP h3 ALPN id for the destination host .IP second.example.com Hostname for the destination host .IP 443 Port number for the destination host .IP 2019 Expiration date and time of this entry within double quotes. The date format is "YYYYMMDD HH:MM:SS" and the time zone is GMT. .IP 1 Boolean (1 or 0) if "persist" was set for this entry .IP 0 Integer priority value (not currently used) .SH AVAILABILITY Added in curl 7.64.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ALTSVC_CTRL (3), .BR CURLOPT_CONNECT_TO (3), .BR CURLOPT_COOKIEFILE (3), .BR CURLOPT_RESOLVE (3)	2.52 KB	2025-07-08 09:41
📄 CURLOPT_ALTSVC_CTRL.3 .\" generated by cd2nroff 0.1 from CURLOPT_ALTSVC_CTRL.md .TH CURLOPT_ALTSVC_CTRL 3 "2025-06-27" libcurl .SH NAME CURLOPT_ALTSVC_CTRL \- control alt\-svc behavior .SH SYNOPSIS .nf #include <curl/curl.h> #define CURLALTSVC_READONLYFILE (1<<2) #define CURLALTSVC_H1 (1<<3) #define CURLALTSVC_H2 (1<<4) #define CURLALTSVC_H3 (1<<5) CURLcode curl_easy_setopt(CURL handle, CURLOPT_ALTSVC_CTRL, long bitmask); .fi .SH DESCRIPTION Populate the long \fIbitmask\fP with the correct set of features to instruct libcurl how to handle Alt\-Svc for the transfers using this handle. libcurl only accepts Alt\-Svc headers over a Secure Transport, meaning HTTPS. It also only completes a request to an alternative origin if that origin is properly hosted over HTTPS. These requirements are there to make sure both the source and the destination are legitimate. Alternative services are only used when setting up new connections. If there exists an existing connection to the host in the connection pool, then that is preferred. If \fICURLOPT_ALTSVC(3)\fP is set, \fICURLOPT_ALTSVC_CTRL(3)\fP gets a default value corresponding to CURLALTSVC_H1 \| CURLALTSVC_H2 \| CURLALTSVC_H3 \- the HTTP/2 and HTTP/3 bits are only set if libcurl was built with support for those versions. Setting any bit enables the alt\-svc engine. .IP CURLALTSVC_READONLYFILE Do not write the alt\-svc cache back to the file specified with \fICURLOPT_ALTSVC(3)\fP even if it gets updated. By default a file specified with that option is read and written to as deemed necessary. .IP CURLALTSVC_H1 Accept alternative services offered over HTTP/1.1. .IP CURLALTSVC_H2 Accept alternative services offered over HTTP/2. This is only used if libcurl was also built to actually support HTTP/2, otherwise this bit is ignored. .IP CURLALTSVC_H3 Accept alternative services offered over HTTP/3. This is only used if libcurl was also built to actually support HTTP/3, otherwise this bit is ignored. .SH DEFAULT 0 \- Alt\-Svc handling is disabled .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_ALTSVC_CTRL, (long)CURLALTSVC_H1); curl_easy_setopt(curl, CURLOPT_ALTSVC, "altsvc-cache.txt"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.64.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ALTSVC (3), .BR CURLOPT_CONNECT_TO (3), .BR CURLOPT_RESOLVE (3)	2.59 KB	2025-07-08 09:41
📄 CURLOPT_APPEND.3 .\" generated by cd2nroff 0.1 from CURLOPT_APPEND.md .TH CURLOPT_APPEND 3 "2025-06-27" libcurl .SH NAME CURLOPT_APPEND \- append to the remote file .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_APPEND, long append); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to append to the remote file instead of overwrite it. This is only useful when uploading to an FTP site. .SH DEFAULT 0 (disabled) .SH PROTOCOLS This functionality affects ftp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); curl_easy_setopt(curl, CURLOPT_APPEND, 1L); curl_easy_perform(curl); } } .fi .SH HISTORY This option was known as CURLOPT_FTPAPPEND up to 7.16.4 .SH AVAILABILITY Added in curl 7.17.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DIRLISTONLY (3), .BR CURLOPT_RESUME_FROM (3), .BR CURLOPT_UPLOAD (3)	1.17 KB	2025-07-08 09:41
📄 CURLOPT_AUTOREFERER.3 .\" generated by cd2nroff 0.1 from CURLOPT_AUTOREFERER.md .TH CURLOPT_AUTOREFERER 3 "2025-06-27" libcurl .SH NAME CURLOPT_AUTOREFERER \- automatically update the referer header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_AUTOREFERER, long autorefer); .fi .SH DESCRIPTION Pass a long parameter set to 1 to enable this. When enabled, libcurl automatically sets the Referer: header field in HTTP requests to the full URL when it follows a Location: redirect to a new destination. The automatic referer is set to the full previous URL even when redirects are done cross\-origin or following redirects to insecure protocols. This is considered a minor privacy leak by some. With \fICURLINFO_REFERER(3)\fP, applications can extract the actually used referer header after the transfer. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* follow redirects / curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); / set Referer: automatically when following redirects */ curl_easy_setopt(curl, CURLOPT_AUTOREFERER, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_EFFECTIVE_URL (3), .BR CURLINFO_REDIRECT_URL (3), .BR CURLINFO_REFERER (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR CURLOPT_REFERER (3)	1.69 KB	2025-07-08 09:41
📄 CURLOPT_AWS_SIGV4.3 .\" generated by cd2nroff 0.1 from CURLOPT_AWS_SIGV4.md .TH CURLOPT_AWS_SIGV4 3 "2025-06-27" libcurl .SH NAME CURLOPT_AWS_SIGV4 \- V4 signature .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_AWS_SIGV4, char param); .fi .SH DESCRIPTION Provides AWS V4 signature authentication on HTTP(S) header. Pass a char pointer that is the collection of specific arguments are used for creating outgoing authentication headers. The format of the \fIparam\fP option is: .IP provider1[:provider2[:region[:service]]] .IP "provider1, provider2" The providers arguments are used for generating some authentication parameters such as "Algorithm", "date", "request type" and "signed headers". .IP region The argument is a geographic area of a resources collection. It is extracted from the hostname specified in the URL if omitted. .IP service The argument is a function provided by a cloud. It is extracted from the hostname specified in the URL if omitted. .PP NOTE: This call set \fICURLOPT_HTTPAUTH(3)\fP to CURLAUTH_AWS_SIGV4. Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same as calling this with \fB"aws:amz"\fP in parameter. Example with "Test:Try", when curl uses the algorithm, it generates \fB"TEST\-HMAC\-SHA256"\fP for "Algorithm", \fB"x\-try\-date"\fP and \fB"X\-Try\-Date"\fP for "date", \fB"test4_request"\fP for "request type", \fB"SignedHeaders=content\-type;host;x\-try\-date"\fP for "signed headers" If you use just "test", instead of "test:try", test is used for every generated string. Setting \fICURLOPT_HTTPAUTH(3)\fP with the CURLAUTH_AWS_SIGV4 bit set is the same as setting this option with a \fB"aws:amz"\fP parameter. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://service.region.example.com/uri"); curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2"); / service and region can also be set in CURLOPT_AWS_SIGV4 */ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); curl_easy_setopt(curl, CURLOPT_AWS_SIGV4, "provider1:provider2:region:service"); curl_easy_setopt(curl, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); curl_easy_perform(curl); } } .fi .SH NOTES This option overrides the other auth types you might have set in \fICURLOPT_HTTPAUTH(3)\fP which should be highlighted as this makes this auth method special. This method cannot be combined with other auth types. A sha256 checksum of the request payload is used as input to the signature calculation. For POST requests, this is a checksum of the provided \fICURLOPT_POSTFIELDS(3)\fP. Otherwise, it is the checksum of an empty buffer. For requests like PUT, you can provide your own checksum in an HTTP header named \fBx\-provider2\-content\-sha256\fP. For \fBaws:s3\fP, a \fBx\-amz\-content\-sha256\fP header is added to every request if not already present. For s3 requests with unknown payload, this header takes the special value "UNSIGNED\-PAYLOAD". .SH AVAILABILITY Added in curl 7.75.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADEROPT (3), .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_PROXYAUTH (3)	3.62 KB	2025-07-08 09:41
📄 CURLOPT_BUFFERSIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_BUFFERSIZE.md .TH CURLOPT_BUFFERSIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_BUFFERSIZE \- receive buffer size .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_BUFFERSIZE, long size); .fi .SH DESCRIPTION Pass a long specifying your preferred \fIsize\fP (in bytes) for the receive buffer in libcurl. The main point of this would be that the write callback gets called more often and with smaller chunks. Secondly, for some protocols, there is a benefit of having a larger buffer for performance. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. This buffer size is by default \fICURL_MAX_WRITE_SIZE\fP (16kB). The maximum buffer size allowed to be set is \fICURL_MAX_READ_SIZE\fP (10MB). The minimum buffer size allowed to be set is 1024. DO NOT set this option on a handle that is currently used for an active transfer as that may lead to unintended consequences. The maximum size was 512kB until 7.88.0. Starting in libcurl 8.7.0, there is just a single transfer buffer allocated per multi handle. This buffer is used by all easy handles added to a multi handle no matter how many parallel transfers there are. The buffer remains allocated as long as there are active transfers. .SH DEFAULT CURL_MAX_WRITE_SIZE (16kB) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); /* ask libcurl to allocate a larger receive buffer */ curl_easy_setopt(curl, CURLOPT_BUFFERSIZE, 120000L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAXFILESIZE (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_UPLOAD_BUFFERSIZE (3), .BR CURLOPT_WRITEFUNCTION (3)	2.11 KB	2025-07-08 09:41
📄 CURLOPT_CAINFO.3 .\" generated by cd2nroff 0.1 from CURLOPT_CAINFO.md .TH CURLOPT_CAINFO 3 "2025-06-27" libcurl .SH NAME CURLOPT_CAINFO \- path to Certificate Authority (CA) bundle .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CAINFO, char path); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a file holding one or more certificates to verify the peer with. If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server\(aqs certificate, \fICURLOPT_CAINFO(3)\fP need not even indicate an accessible file. This option is by default set to the system path where libcurl\(aqs CA certificate bundle is assumed to be stored, as established at build time. (iOS and macOS) When curl uses Secure Transport this option is supported. If the option is not set, then curl uses the certificates in the system and user Keychain to verify the peer. (Schannel) This option is supported for Schannel in Windows 7 or later but we recommend not using it until Windows 8 since it works better starting then. If the option is not set, then curl uses the certificates in the Windows\(aq store of root certificates (the default for Schannel). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. .SH DEFAULT Built\-in system specific. When curl is built with Secure Transport or Schannel, this option is not set by default. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_CAINFO, "/etc/certs/cabundle.pem"); curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY Schannel support added in libcurl 7.60. .SH AVAILABILITY Added in curl 7.4.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAINFO (3), .BR CURLOPT_CAINFO_BLOB (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_CA_CACHE_TIMEOUT (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.46 KB	2025-07-08 09:41
📄 CURLOPT_CAINFO_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_CAINFO_BLOB.md .TH CURLOPT_CAINFO_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_CAINFO_BLOB \- Certificate Authority (CA) bundle in PEM format .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CAINFO_BLOB, struct curl_blob stblob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure, which contains information (pointer and size) about a memory block with binary data of PEM encoded content holding one or more certificates to verify the HTTPS server with. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. If \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server\(aqs certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed. This option overrides \fICURLOPT_CAINFO(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL .SH EXAMPLE .nf #include <string.h> int main(void) { char strpem = "PEMDATA"; / strpem must point to a PEM string / CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); blob.data = strpem; blob.len = strlen(strpem); blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_CAINFO_BLOB, &blob); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option is supported by the BearSSL (since 7.79.0), mbedTLS (since 7.81.0), Rustls (since 7.82.0), wolfSSL (since 8.2.0), OpenSSL, Secure Transport and Schannel backends. .SH AVAILABILITY Added in curl 7.77.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.17 KB	2025-07-08 09:41
📄 CURLOPT_CAPATH.3 .\" generated by cd2nroff 0.1 from CURLOPT_CAPATH.md .TH CURLOPT_CAPATH 3 "2025-06-27" libcurl .SH NAME CURLOPT_CAPATH \- directory holding CA certificates .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CAPATH, char capath); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the OpenSSL c_rehash utility. This makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. The \fICURLOPT_CAPATH(3)\fP function apparently does not work in Windows due to some limitation in OpenSSL. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. .SH DEFAULT A path detected at build time. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_CAPATH, "/etc/cert-dir"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.8 .SH RETURN VALUE CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN \- Not supported by the SSL backend CURLE_UNKNOWN_OPTION CURLE_OUT_OF_MEMORY .SH SEE ALSO .BR CURLINFO_CAPATH (3), .BR CURLOPT_CAINFO (3), .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3)	1.83 KB	2025-07-08 09:41
📄 CURLOPT_CA_CACHE_TIMEOUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_CA_CACHE_TIMEOUT.md .TH CURLOPT_CA_CACHE_TIMEOUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_CA_CACHE_TIMEOUT \- life\-time for cached certificate stores .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CA_CACHE_TIMEOUT, long age); .fi .SH DESCRIPTION Pass a long, this sets the timeout in seconds. This tells libcurl the maximum time any cached CA certificate store it has in memory may be kept and reused for new connections. Once the timeout has expired, a subsequent fetch requiring a CA certificate has to reload it. Building a CA certificate store from a \fICURLOPT_CAINFO(3)\fP file is a slow operation so curl may cache the generated certificate store internally to speed up future connections. Set the timeout to zero to completely disable caching, or set to \-1 to retain the cached store remain forever. By default, libcurl caches this info for 24 hours. .SH DEFAULT 86400 (24 hours) .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel and wolfSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* only reuse certificate stores for a short time / curl_easy_setopt(curl, CURLOPT_CA_CACHE_TIMEOUT, 60L); res = curl_easy_perform(curl); / in this second request, the cache is not used if more than sixty seconds passed since the previous connection */ res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option is supported by OpenSSL and its forks (since 7.87.0), Schannel (since 8.5.0), wolfSSL (since 8.9.0) and GnuTLS (since 8.9.0). .SH AVAILABILITY Added in curl 7.87.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAINFO_BLOB (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.18 KB	2025-07-08 09:41
📄 CURLOPT_CERTINFO.3 .\" generated by cd2nroff 0.1 from CURLOPT_CERTINFO.md .TH CURLOPT_CERTINFO 3 "2025-06-27" libcurl .SH NAME CURLOPT_CERTINFO \- request SSL certificate information .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CERTINFO, long certinfo); .fi .SH DESCRIPTION Pass a long set to 1 to enable libcurl\(aqs certificate chain info gatherer. With this enabled, libcurl extracts lots of information and data about the certificates in the certificate chain used in the SSL connection. This data may then be retrieved after a transfer using \fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport and rustls .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); /* connect to any HTTPS site, trusted or not / curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L); curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L); curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L); res = curl_easy_perform(curl); if(!res) { struct curl_certinfo ci; res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci); if(!res) { int i; printf("%d certs!\\n", ci->num_of_certs); for(i = 0; i < ci->num_of_certs; i++) { struct curl_slist *slist; for(slist = ci->certinfo[i]; slist; slist = slist->next) printf("%s\\n", slist->data); } } } curl_easy_cleanup(curl); } } .fi .SH HISTORY Schannel support added in 7.50.0. Secure Transport support added in 7.79.0. mbedTLS support added in 8.9.0. .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAINFO (3), .BR CURLINFO_CAPATH (3), .BR CURLINFO_CERTINFO (3), .BR CURLOPT_CAINFO (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.19 KB	2025-07-08 09:41
📄 CURLOPT_CHUNK_BGN_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_BGN_FUNCTION.md .TH CURLOPT_CHUNK_BGN_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcard match .SH SYNOPSIS .nf #include <curl/curl.h> struct curl_fileinfo { char filename; curlfiletype filetype; time_t time; / always zero / unsigned int perm; int uid; int gid; curl_off_t size; long int hardlinks; struct { / If some of these fields is not NULL, it is a pointer to b_data. / char time; char perm; char user; char group; char target; /* pointer to the target filename of a symlink / } strings; unsigned int flags; / used internally / char b_data; size_t b_size; size_t b_used; }; long chunk_bgn_callback(const void transfer_info, void ptr, int remains); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CHUNK_BGN_FUNCTION, chunk_bgn_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl before a part of the stream is going to be transferred (if the transfer supports chunks). The \fItransfer_info\fP pointer points to a \fBcurl_fileinfo\fP struct with details about the file that is about to get transferred. This callback makes sense only when using the \fICURLOPT_WILDCARDMATCH(3)\fP option for now. The target of transfer_info parameter is a "feature depended" structure. For the FTP wildcard download, the target is \fBcurl_fileinfo\fP structure (see \fIcurl/curl.h\fP). The parameter \fIptr\fP is a pointer given by \fICURLOPT_CHUNK_DATA(3)\fP. The parameter remains contains number of chunks remaining per the transfer. If the feature is not available, the parameter has zero value. Return \fICURL_CHUNK_BGN_FUNC_OK\fP if everything is fine, \fICURL_CHUNK_BGN_FUNC_SKIP\fP if you want to skip the concrete chunk or \fICURL_CHUNK_BGN_FUNC_FAIL\fP to tell libcurl to stop if some error occurred. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf #include <stdio.h> struct callback_data { FILE output; }; static long file_is_coming(struct curl_fileinfo finfo, void ptr, int remains) { struct callback_data data = ptr; printf("%3d %40s %10luB ", remains, finfo->filename, (unsigned long)finfo->size); switch(finfo->filetype) { case CURLFILETYPE_DIRECTORY: printf(" DIR\\n"); break; case CURLFILETYPE_FILE: printf("FILE "); break; default: printf("OTHER\\n"); break; } if(finfo->filetype == CURLFILETYPE_FILE) { / do not transfer files >= 50B / if(finfo->size > 50) { printf("SKIPPED\\n"); return CURL_CHUNK_BGN_FUNC_SKIP; } data->output = fopen(finfo->filename, "wb"); if(!data->output) { return CURL_CHUNK_BGN_FUNC_FAIL; } } return CURL_CHUNK_BGN_FUNC_OK; } int main() { / data for callback / struct callback_data callback_info; CURL curl = curl_easy_init(); /* callback is called before download of concrete file started */ curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CHUNK_END_FUNCTION (3), .BR CURLOPT_WILDCARDMATCH (3)	3.56 KB	2025-07-08 09:41
📄 CURLOPT_CHUNK_DATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_DATA.md .TH CURLOPT_CHUNK_DATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_CHUNK_DATA \- pointer passed to the FTP chunk callbacks .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CHUNK_DATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the ptr argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf #include <stdio.h> struct callback_data { FILE output; }; static long file_is_coming(struct curl_fileinfo finfo, void ptr, int remains) { struct callback_data data = ptr; printf("%3d %40s %10luB ", remains, finfo->filename, (unsigned long)finfo->size); switch(finfo->filetype) { case CURLFILETYPE_DIRECTORY: printf(" DIR\\n"); break; case CURLFILETYPE_FILE: printf("FILE "); break; default: printf("OTHER\\n"); break; } if(finfo->filetype == CURLFILETYPE_FILE) { /* do not transfer files >= 50B / if(finfo->size > 50) { printf("SKIPPED\\n"); return CURL_CHUNK_BGN_FUNC_SKIP; } data->output = fopen(finfo->filename, "wb"); if(!data->output) { return CURL_CHUNK_BGN_FUNC_FAIL; } } return CURL_CHUNK_BGN_FUNC_OK; } int main() { / data for callback / struct callback_data callback_info; CURL curl = curl_easy_init(); /* callback is called before download of concrete file started */ curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CHUNK_BGN_FUNCTION (3), .BR CURLOPT_WILDCARDMATCH (3)	2.02 KB	2025-07-08 09:41
📄 CURLOPT_CHUNK_END_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CHUNK_END_FUNCTION.md .TH CURLOPT_CHUNK_END_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcard match .SH SYNOPSIS .nf #include <curl/curl.h> long chunk_end_callback(void ptr); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CHUNK_END_FUNCTION, chunk_end_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This function gets called by libcurl as soon as a part of the stream has been transferred (or skipped). Return \fICURL_CHUNK_END_FUNC_OK\fP if everything is fine or \fBCURL_CHUNK_END_FUNC_FAIL\fP to tell the lib to stop if some error occurred. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf #include <stdio.h> struct callback_data { FILE output; }; static long file_is_downloaded(void ptr) { struct callback_data data = ptr; if(data->output) { fclose(data->output); data->output = 0x0; } return CURL_CHUNK_END_FUNC_OK; } int main() { / data for callback / struct callback_data callback_info; CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); curl_easy_setopt(curl, CURLOPT_CHUNK_DATA, &callback_info); } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CHUNK_BGN_FUNCTION (3), .BR CURLOPT_WILDCARDMATCH (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_CLOSESOCKETDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_CLOSESOCKETDATA.md .TH CURLOPT_CLOSESOCKETDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_CLOSESOCKETDATA \- pointer passed to the socket close callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CLOSESOCKETDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that remains untouched by libcurl and passed as the first argument in the closesocket callback set with \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int closesocket(void clientp, curl_socket_t item) { struct priv my = clientp; printf("our ptr: %p\\n", my->custom); printf("libcurl wants to close %d now\\n", (int)item); return 0; } int main(void) { struct priv myown; CURL curl = curl_easy_init(); /* call this function to close sockets */ curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); curl_easy_perform(curl); curl_easy_cleanup(curl); } .fi .SH AVAILABILITY Added in curl 7.21.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CLOSESOCKETFUNCTION (3), .BR CURLOPT_OPENSOCKETFUNCTION (3)	1.45 KB	2025-07-08 09:41
📄 CURLOPT_CLOSESOCKETFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CLOSESOCKETFUNCTION.md .TH CURLOPT_CLOSESOCKETFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement .SH SYNOPSIS .nf #include <curl/curl.h> int closesocket_callback(void clientp, curl_socket_t item); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CLOSESOCKETFUNCTION, closesocket_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl instead of the \fIclose(3)\fP or \fIclosesocket(3)\fP call when sockets are closed (not for any other file descriptors). This is pretty much the reverse to the \fICURLOPT_OPENSOCKETFUNCTION(3)\fP option. Return 0 to signal success and 1 if there was an error. The \fIclientp\fP pointer is set with \fICURLOPT_CLOSESOCKETDATA(3)\fP. \fIitem\fP is the socket libcurl wants to be closed. .SH DEFAULT Use the standard socket close function. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int closesocket(void clientp, curl_socket_t item) { struct priv my = clientp; printf("our ptr: %p\\n", my->custom); printf("libcurl wants to close %d now\\n", (int)item); return 0; } int main(void) { struct priv myown; CURL curl = curl_easy_init(); /* call this function to close sockets */ curl_easy_setopt(curl, CURLOPT_CLOSESOCKETFUNCTION, closesocket); curl_easy_setopt(curl, CURLOPT_CLOSESOCKETDATA, &myown); curl_easy_perform(curl); curl_easy_cleanup(curl); } .fi .SH AVAILABILITY Added in curl 7.21.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CLOSESOCKETDATA (3), .BR CURLOPT_OPENSOCKETFUNCTION (3)	1.9 KB	2025-07-08 09:41
📄 CURLOPT_CONNECTTIMEOUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONNECTTIMEOUT.md .TH CURLOPT_CONNECTTIMEOUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONNECTTIMEOUT \- timeout for the connect phase .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONNECTTIMEOUT, long timeout); .fi .SH DESCRIPTION Pass a long. It sets the maximum time in seconds that you allow the connection phase to take. This timeout only limits the connection phase, it has no impact once libcurl has connected. The connection phase includes the name resolve (DNS) and all protocol handshakes and negotiations until there is an established connection with the remote side. Set this option to zero to switch to the default built\-in connection timeout \- 300 seconds. See also the \fICURLOPT_TIMEOUT(3)\fP option. \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP is the same function but set in milliseconds. If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP are set, the value set last is used. The connection timeout is included in the general all\-covering \fICURLOPT_TIMEOUT(3)\fP: With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set to 5, the operation can never last longer than 5 seconds, and the connection phase cannot last longer than 3 seconds. With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set to 2, the operation can never last longer than 2 seconds. Including the connection phase. This option may cause libcurl to use the SIGALRM signal to timeout system calls on builds not using asynch DNS. In Unix\-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. .SH DEFAULT 300 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* complete connection within 10 seconds */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT, 10L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_TIMEOUT (3)	2.33 KB	2025-07-08 09:41
📄 CURLOPT_CONNECTTIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONNECTTIMEOUT_MS.md .TH CURLOPT_CONNECTTIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONNECTTIMEOUT_MS \- timeout for the connect phase .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONNECTTIMEOUT_MS, long timeout); .fi .SH DESCRIPTION Pass a long. It sets the maximum time in milliseconds that you allow the connection phase to take. This timeout only limits the connection phase, it has no impact once libcurl has connected. The connection phase includes the name resolve (DNS) and all protocol handshakes and negotiations until there is an established connection with the remote side. Set this option to zero to switch to the default built\-in connection timeout \- 300 seconds. See also the \fICURLOPT_TIMEOUT_MS(3)\fP option. \fICURLOPT_CONNECTTIMEOUT(3)\fP is the same function but set in seconds. If both \fICURLOPT_CONNECTTIMEOUT(3)\fP and \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP are set, the value set last is used. The connection timeout is included in the general all\-covering \fICURLOPT_TIMEOUT_MS(3)\fP: With \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP set to 3000 and \fICURLOPT_TIMEOUT_MS(3)\fP set to 5000, the operation can never last longer than 5000 milliseconds, and the connection phase cannot last longer than 3000 milliseconds. With \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP set to 4000 and \fICURLOPT_TIMEOUT_MS(3)\fP set to 2000, the operation can never last longer than 2000 milliseconds. Including the connection phase. This option may cause libcurl to use the SIGALRM signal to timeout system calls on builds not using asynch DNS. In Unix\-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. .SH DEFAULT 300000 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* complete connection within 10000 milliseconds */ curl_easy_setopt(curl, CURLOPT_CONNECTTIMEOUT_MS, 10000L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_TIMEOUT_MS (3)	2.44 KB	2025-07-08 09:41
📄 CURLOPT_CONNECT_ONLY.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONNECT_ONLY.md .TH CURLOPT_CONNECT_ONLY 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONNECT_ONLY \- stop when connected to target server .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONNECT_ONLY, long only); .fi .SH DESCRIPTION Pass a long. If the parameter equals 1, it tells the library to perform all the required proxy authentication and connection setup, but no data transfer, and then return. The option can be used to simply test a connection to a server, but is more useful when used with the \fICURLINFO_ACTIVESOCKET(3)\fP option to \fIcurl_easy_getinfo(3)\fP as the library can set up the connection and then the application can obtain the most recently used socket for special data transfers. Since 7.86.0, this option can be set to \(aq2\(aq and if HTTP or WebSocket are used, libcurl performs the request and reads all response headers before handing over control to the application. Transfers marked connect only do not reuse any existing connections and connections marked connect only are not allowed to get reused. If the connect only transfer is done using the multi interface, the particular easy handle must remain added to the multi handle for as long as the application wants to use it. Once it has been removed with \fIcurl_multi_remove_handle(3)\fP, \fIcurl_easy_send(3)\fP and \fIcurl_easy_recv(3)\fP do not function. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); ret = curl_easy_perform(curl); if(ret == CURLE_OK) { /* only connected */ } } } .fi .SH HISTORY WS and WSS support added in 7.86.0. .SH AVAILABILITY Added in curl 7.15.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_VERBOSE (3), .BR curl_easy_recv (3), .BR curl_easy_send (3)	2.18 KB	2025-07-08 09:41
📄 CURLOPT_CONNECT_TO.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONNECT_TO.md .TH CURLOPT_CONNECT_TO 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONNECT_TO \- connect to another host and port instead .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONNECT_TO, struct curl_slist connect_to); .fi .SH DESCRIPTION Pass a pointer to a linked list of strings with "connect to" information to use for establishing network connections with this handle. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. Each single string should be written using the format HOST:PORT:CONNECT\-TO\-HOST:CONNECT\-TO\-PORT where HOST is the host of the request, PORT is the port of the request, CONNECT\-TO\-HOST is the hostname to connect to, and CONNECT\-TO\-PORT is the port to connect to. The first string that matches the request\(aqs host and port is used. Dotted numerical IP addresses are supported for HOST and CONNECT\-TO\-HOST. A numerical IPv6 address must be written within [brackets]. Any of the four values may be empty. When the HOST or PORT is empty, the host or port always match (the request\(aqs host or port is ignored). When CONNECT\-TO\-HOST or CONNECT\-TO\-PORT is empty, the "connect to" feature is disabled for the host or port, and the request\(aqs host or port are used to establish the network connection. This option is suitable to direct the request at a specific server, e.g. at a specific cluster node in a cluster of servers. The "connect to" host and port are only used to establish the network connection. They do NOT affect the host and port that are used for TLS/SSL (e.g. SNI, certificate verification) or for the application protocols. In contrast to \fICURLOPT_RESOLVE(3)\fP, the option \fICURLOPT_CONNECT_TO(3)\fP does not pre\-populate the DNS cache and therefore it does not affect future transfers of other easy handles that have been added to the same multi handle. The "connect to" host and port are ignored if they are equal to the host and the port in the request URL, because connecting to the host and the port in the request URL is the default behavior. If an HTTP proxy is used for a request having a special "connect to" host or port, and the "connect to" host or port differs from the request\(aqs host and port, the HTTP proxy is automatically switched to tunnel mode for this specific request. This is necessary because it is not possible to connect to a specific host or port in normal (non\-tunnel) mode. When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl; struct curl_slist connect_to = NULL; connect_to = curl_slist_append(NULL, "example.com::server1.example.com:"); curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_CONNECT_TO, connect_to); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); /* always cleanup */ curl_easy_cleanup(curl); } curl_slist_free_all(connect_to); } .fi .SH AVAILABILITY Added in curl 7.49.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FOLLOWLOCATION (3), .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_RESOLVE (3), .BR CURLOPT_URL (3)	3.82 KB	2025-07-08 09:41
📄 CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONV_FROM_NETWORK_FUNCTION.md .TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode conv_callback(char ptr, size_t length); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONV_FROM_NETWORK_FUNCTION, conv_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the \fBCURL_VERSION_CONV\fP feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. The amount of data to convert is indicated by the \fIlength\fP parameter. The converted data overlays the input data in the buffer pointed to by the ptr parameter. \fICURLE_OK\fP must be returned upon successful conversion. A CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, should be returned if an error was encountered. \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP converts to host encoding from the network encoding. It is used when commands or ASCII data are received over the network. If you set a callback pointer to NULL, or do not set it at all, the built\-in libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, the conversion returns the \fBCURLE_CONV_REQD\fP error code. If \fBHAVE_ICONV\fP is defined, \fBCURL_ICONV_CODESET_OF_HOST\fP must also be defined. For example: .nf #define CURL_ICONV_CODESET_OF_HOST "IBM-1047" .fi The iconv code in libcurl defaults the network and UTF8 codeset names as follows: .nf #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" .fi You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static CURLcode my_conv_from_ascii_to_ebcdic(char buffer, size_t length) { int rc = 0; / in-place convert 'buffer' from ASCII to EBCDIC / if(rc == 0) { / success / return CURLE_OK; } else { return CURLE_CONV_FAILED; } } int main(void) { CURL curl = curl_easy_init(); /* use platform-specific functions for codeset conversions */ curl_easy_setopt(curl, CURLOPT_CONV_FROM_NETWORK_FUNCTION, my_conv_from_ascii_to_ebcdic); } .fi .SH DEPRECATED Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3), .BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3)	2.95 KB	2025-07-08 09:41
📄 CURLOPT_CONV_FROM_UTF8_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONV_FROM_UTF8_FUNCTION.md .TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode conv_callback(char ptr, size_t length); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONV_FROM_UTF8_FUNCTION, conv_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the CURL_VERSION_CONV feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. The amount of data to convert is indicated by the \fIlength\fP parameter. The converted data overlays the input data in the buffer pointed to by the ptr parameter. \fICURLE_OK\fP must be returned upon successful conversion. A CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, should be returned if an error was encountered. \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP converts to host encoding from UTF8 encoding. It is required only for SSL processing. If you set a callback pointer to NULL, or do not set it at all, the built\-in libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, the conversion returns the CURLE_CONV_REQD error code. If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. For example: .nf #define CURL_ICONV_CODESET_OF_HOST "IBM-1047" .fi The iconv code in libcurl defaults the network and UTF8 codeset names as follows: .nf #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" .fi You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static CURLcode my_conv_from_utf8_to_ebcdic(char buffer, size_t length) { int rc = 0; / in-place convert 'buffer' from UTF-8 to EBCDIC / if(rc == 0) { / success / return CURLE_OK; } else { return CURLE_CONV_FAILED; } } int main(void) { CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_CONV_FROM_UTF8_FUNCTION, my_conv_from_utf8_to_ebcdic); } .fi .SH DEPRECATED Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), .BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3)	2.8 KB	2025-07-08 09:41
📄 CURLOPT_CONV_TO_NETWORK_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_CONV_TO_NETWORK_FUNCTION.md .TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode conv_callback(char ptr, size_t length); CURLcode curl_easy_setopt(CURL handle, CURLOPT_CONV_TO_NETWORK_FUNCTION, conv_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. Applies to non\-ASCII platforms. \fIcurl_version_info(3)\fP returns the CURL_VERSION_CONV feature bit set if this option is provided. The data to be converted is in a buffer pointed to by the \fIptr\fP parameter. The amount of data to convert is indicated by the \fIlength\fP parameter. The converted data overlays the input data in the buffer pointed to by the ptr parameter. \fICURLE_OK\fP must be returned upon successful conversion. A CURLcode return value defined by curl.h, such as \fICURLE_CONV_FAILED\fP, should be returned if an error was encountered. \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP converts from host encoding to the network encoding. It is used when commands or ASCII data are sent over the network. If you set a callback pointer to NULL, or do not set it at all, the built\-in libcurl iconv functions are used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, the conversion returns the CURLE_CONV_REQD error code. If HAVE_ICONV is defined, CURL_ICONV_CODESET_OF_HOST must also be defined. For example: .nf define CURL_ICONV_CODESET_OF_HOST "IBM-1047" .fi The iconv code in libcurl defaults the network and UTF8 codeset names as follows: .nf #define CURL_ICONV_CODESET_OF_NETWORK "ISO8859-1" #define CURL_ICONV_CODESET_FOR_UTF8 "UTF-8" .fi You need to override these definitions if they are different on your system. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static CURLcode my_conv_from_ebcdic_to_ascii(char buffer, size_t length) { int rc = 0; / in-place convert 'buffer' from EBCDIC to ASCII / if(rc == 0) { / success / return CURLE_OK; } else { return CURLE_CONV_FAILED; } } int main(void) { CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_CONV_TO_NETWORK_FUNCTION, my_conv_from_ebcdic_to_ascii); } .fi .SH DEPRECATED Not available and deprecated since 7.82.0. Available only if \fBCURL_DOES_CONVERSIONS\fP was defined when libcurl was built. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), .BR CURLOPT_CONV_FROM_UTF8_FUNCTION (3)	2.85 KB	2025-07-08 09:41
📄 CURLOPT_COOKIE.3 .\" generated by cd2nroff 0.1 from CURLOPT_COOKIE.md .TH CURLOPT_COOKIE 3 "2025-06-27" libcurl .SH NAME CURLOPT_COOKIE \- HTTP Cookie header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COOKIE, char cookie); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It is used to set one or more cookies in the HTTP request. The format of the string should be NAME=CONTENTS, where NAME is the cookie name and CONTENTS is what the cookie should contain. To set multiple cookies, set them all using a single option concatenated like this: "name1=content1; name2=content2;" etc. libcurl does not syntax check the data but assumes the application gives it what it needs to send. This option sets the cookie header explicitly in the outgoing request(s). If multiple requests are done due to authentication, followed redirections or similar, they all get this cookie passed on. The cookies set by this option are separate from the internal cookie storage held by the cookie engine and they are not be modified by it. If you enable the cookie engine and either you have imported a cookie of the same name (e.g. \(aqfoo\(aq) or the server has set one, it has no effect on the cookies you set here. A request to the server sends both the \(aqfoo\(aq held by the cookie engine and the \(aqfoo\(aq held by this option. To set a cookie that is instead held by the cookie engine and can be modified by the server use \fICURLOPT_COOKIELIST(3)\fP. Since this custom cookie is appended to the Cookie: header in addition to any cookies set by the cookie engine, there is a risk that the header ends up too long and thereby getting the entire request rejected by the server. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. This option does not enable the cookie engine. Use \fICURLOPT_COOKIEFILE(3)\fP or \fICURLOPT_COOKIEJAR(3)\fP to enable parsing and sending cookies automatically. .SH DEFAULT NULL, no cookies .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_COOKIE, "tool=curl; fun=yes;"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_COOKIELIST (3), .BR CURLOPT_COOKIEFILE (3), .BR CURLOPT_COOKIEJAR (3), .BR CURLOPT_COOKIELIST (3), .BR CURLOPT_HTTPHEADER (3)	2.75 KB	2025-07-08 09:41
📄 CURLOPT_COOKIEFILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_COOKIEFILE.md .TH CURLOPT_COOKIEFILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_COOKIEFILE \- filename to read cookies from .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COOKIEFILE, char filename); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It should point to the filename of your file holding cookie data to read. The cookie data can be in either the old Netscape / Mozilla cookie data format or just regular HTTP headers (Set\-Cookie style) dumped to a file. It also enables the cookie engine, making libcurl parse and send cookies on subsequent requests with this handle. By passing the empty string ("") to this option, you enable the cookie engine without reading any initial cookies. If you tell libcurl the filename is "\-" (just a single minus sign), libcurl instead reads from stdin. This option only \fBreads\fP cookies. To make libcurl write cookies to file, see \fICURLOPT_COOKIEJAR(3)\fP. If you read cookies from a plain HTTP headers file and it does not specify a domain in the Set\-Cookie line, then the cookie is not sent since the cookie domain cannot match the target URL\(aqs. To address this, set a domain in Set\-Cookie line (doing that includes subdomains) or preferably: use the Netscape format. The application does not have to keep the string around after setting this option. If you use this option multiple times, you add more files to read cookies from. Setting this option to NULL disables the cookie engine and clears the list of files to read cookies from. .SH SECURITY CONCERNS This document previously mentioned how specifying a non\-existing file can also enable the cookie engine. While true, we strongly advise against using that method as it is too hard to be sure that files that stay that way in the long run. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); / get cookies from an existing file */ curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH Cookie file format The cookie file format and general cookie concepts in curl are described online here: https://curl.se/docs/http\-cookies.html .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COOKIE (3), .BR CURLOPT_COOKIEJAR (3), .BR CURLOPT_COOKIESESSION (3)	2.71 KB	2025-07-08 09:41
📄 CURLOPT_COOKIEJAR.3 .\" generated by cd2nroff 0.1 from CURLOPT_COOKIEJAR.md .TH CURLOPT_COOKIEJAR 3 "2025-06-27" libcurl .SH NAME CURLOPT_COOKIEJAR \- filename to store cookies to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COOKIEJAR, char filename); .fi .SH DESCRIPTION Pass a \fIfilename\fP as a char , null\-terminated. This makes libcurl write all internally known cookies to the specified file when \fIcurl_easy_cleanup(3)\fP is called. If no cookies are kept in memory at that time, no file is created. Specify "\-" as filename to instead have the cookies written to stdout. Using this option also enables cookies for this session, so if you for example follow a redirect it makes matching cookies get sent accordingly. Note that libcurl does not read any cookies from the cookie jar specified with this option. To read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. If the cookie jar file cannot be created or written to (when the \fIcurl_easy_cleanup(3)\fP is called), libcurl does not and cannot report an error for this. Using \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP displays a warning, but that is the only visible feedback you get about this possibly lethal situation. Cookies are imported in the Set\-Cookie format without a domain name are not exported by this option. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH SECURITY CONCERNS libcurl cannot fully protect against attacks where an attacker has write access to the same directory where it is directed to save files. This is particularly sensitive if you save files using elevated privileges. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* export cookies to this file when closing the handle / curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "/tmp/cookies.txt"); res = curl_easy_perform(curl); / close the handle, write the cookies */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COOKIE (3), .BR CURLOPT_COOKIEFILE (3), .BR CURLOPT_COOKIELIST (3)	2.54 KB	2025-07-08 09:41
📄 CURLOPT_COOKIELIST.3 .\" generated by cd2nroff 0.1 from CURLOPT_COOKIELIST.md .TH CURLOPT_COOKIELIST 3 "2025-06-27" libcurl .SH NAME CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COOKIELIST, char cookie); .fi .SH DESCRIPTION Pass a char pointer to a \fIcookie\fP string. Such a cookie can be either a single line in Netscape / Mozilla format or just regular HTTP\-style header (\fISet\-Cookie:\fP) format. This option also enables the cookie engine. This adds that single cookie to the internal cookie store. We strongly advice against loading cookies from an HTTP header file, as that is an inferior data exchange format. Exercise caution if you are using this option and multiple transfers may occur. If you use the \fISet\-Cookie\fP format and the string does not specify a domain, then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server\-set cookie. If a server sets a cookie of the same name (or maybe you have imported one) then both are sent on future transfers to that server, likely not what you intended. To address these issues set a domain in \fISet\-Cookie\fP (doing that includes subdomains) or much better: use the Netscape file format. Additionally, there are commands available that perform actions if you pass in these exact strings: .IP ALL erases all cookies held in memory .IP SESS erases all session cookies held in memory .IP FLUSH writes all known cookies to the file specified by \fICURLOPT_COOKIEJAR(3)\fP .IP RELOAD loads all cookies from the files specified by \fICURLOPT_COOKIEFILE(3)\fP .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf /* an inline import of a cookie in Netscape format. / #define SEP "\\t" / Tab separates the fields / int main(void) { const char my_cookie = "example.com" /* Hostname / SEP "FALSE" / Include subdomains / SEP "/" / Path / SEP "FALSE" / Secure / SEP "0" / Expiry in epoch time format. 0 == Session / SEP "foo" / Name / SEP "bar"; / Value / CURL curl = curl_easy_init(); if(curl) { /* my_cookie is imported immediately via CURLOPT_COOKIELIST. / curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); / The list of cookies in cookies.txt are not be imported until right before a transfer is performed. Cookies in the list that have the same hostname, path and name as in my_cookie are skipped. That is because libcurl has already imported my_cookie and it's considered a "live" cookie. A live cookie is not replaced by one read from a file. / curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); / import / / Cookies are exported after curl_easy_cleanup is called. The server may have added, deleted or modified cookies by then. The cookies that were skipped on import are not exported. / curl_easy_setopt(curl, CURLOPT_COOKIEJAR, "cookies.txt"); / export / curl_easy_perform(curl); / cookies imported from cookies.txt / curl_easy_cleanup(curl); / cookies exported to cookies.txt */ } } .fi .SH Cookie file format The cookie file format and general cookie concepts in curl are described online here: https://curl.se/docs/http\-cookies.html .SH HISTORY \fBALL\fP was added in 7.14.1 \fBSESS\fP was added in 7.15.4 \fBFLUSH\fP was added in 7.17.1 \fBRELOAD\fP was added in 7.39.0 .SH AVAILABILITY Added in curl 7.14.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_COOKIELIST (3), .BR CURLOPT_COOKIE (3), .BR CURLOPT_COOKIEFILE (3), .BR CURLOPT_COOKIEJAR (3)	3.82 KB	2025-07-08 09:41
📄 CURLOPT_COOKIESESSION.3 .\" generated by cd2nroff 0.1 from CURLOPT_COOKIESESSION.md .TH CURLOPT_COOKIESESSION 3 "2025-06-27" libcurl .SH NAME CURLOPT_COOKIESESSION \- start a new cookie session .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COOKIESESSION, long init); .fi .SH DESCRIPTION Pass a long set to 1 to mark this as a new cookie "session". It forces libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session. By default, libcurl always loads all cookies, independent if they are session cookies or not. Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only. A "session" is usually defined in browser land for as long as you have your browser up, more or less. libcurl needs the application to use this option to tell it when a new session starts, otherwise it assumes everything is still in the same session. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* new "session", do not load session cookies / curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L); / get the (non session) cookies from this file */ curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "/tmp/cookies.txt"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COOKIE (3), .BR CURLOPT_COOKIEFILE (3), .BR CURLOPT_COOKIEJAR (3)	1.77 KB	2025-07-08 09:41
📄 CURLOPT_COPYPOSTFIELDS.3 .\" generated by cd2nroff 0.1 from CURLOPT_COPYPOSTFIELDS.md .TH CURLOPT_COPYPOSTFIELDS 3 "2025-06-27" libcurl .SH NAME CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_COPYPOSTFIELDS, char data); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be the full \fIdata\fP to post in a HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but the original data is instead copied by the library, allowing the application to overwrite the original data after setting this option. Because data is copied, care must be taken when using this option in conjunction with \fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. If the size has not been set prior to \fICURLOPT_COPYPOSTFIELDS(3)\fP, the data is assumed to be a null\-terminated string; else the stored size informs the library about the byte count to copy. In any case, the size must not be changed after \fICURLOPT_COPYPOSTFIELDS(3)\fP, unless another \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP option is set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { char local_buffer[1024]="data to send"; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / size of the data to copy from the buffer and send in the request / curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); / send data from the local stack */ curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.17.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_POSTFIELDSIZE (3), .BR CURLOPT_UPLOAD (3)	2.19 KB	2025-07-08 09:41
📄 CURLOPT_CRLF.3 .\" generated by cd2nroff 0.1 from CURLOPT_CRLF.md .TH CURLOPT_CRLF 3 "2025-06-27" libcurl .SH NAME CURLOPT_CRLF \- CRLF conversion .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CRLF, long conv); .fi .SH DESCRIPTION Pass a long. If the value is set to 1 (one), libcurl converts Unix newlines to CRLF newlines on transfers. Disable this option again by setting the value to 0 (zero). This is a legacy option of questionable use. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); curl_easy_setopt(curl, CURLOPT_CRLF, 1L); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONV_FROM_NETWORK_FUNCTION (3), .BR CURLOPT_CONV_TO_NETWORK_FUNCTION (3)	1.13 KB	2025-07-08 09:41
📄 CURLOPT_CRLFILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_CRLFILE.md .TH CURLOPT_CRLFILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_CRLFILE \- Certificate Revocation List file .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CRLFILE, char file); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a \fIfile\fP with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during the SSL exchange. When curl is built to use GnuTLS, there is no way to influence the use of CRL passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed. Also note that \fICURLOPT_CRLFILE(3)\fP implies \fBCURLSSLOPT_NO_PARTIALCHAIN\fP (see \fICURLOPT_SSL_OPTIONS(3)\fP) since curl 7.71.0 due to an OpenSSL bug. This option makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, mbedTLS and rustls .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_CRLFILE, "/etc/certs/crl.pem"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_CRLFILE (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.37 KB	2025-07-08 09:41
📄 CURLOPT_CURLU.3 .\" generated by cd2nroff 0.1 from CURLOPT_CURLU.md .TH CURLOPT_CURLU 3 "2025-06-27" libcurl .SH NAME CURLOPT_CURLU \- URL in URL handle format .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CURLU, CURLU pointer); .fi .SH DESCRIPTION Pass in a pointer to the \fIURL\fP handle to work with. The parameter should be a \fICURLU pointer\fP. Setting \fICURLOPT_CURLU(3)\fP explicitly overrides \fICURLOPT_URL(3)\fP. \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a transfer is started. libcurl uses this handle and its contents read\-only and does not change its contents. An application can update the contents of the URL handle after a transfer is done and if the same handle is used in a subsequent request the updated contents is used. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); CURLU urlp = curl_url(); if(curl) { CURLcode res; CURLUcode ret; ret = curl_url_set(urlp, CURLUPART_URL, "https://example.com", 0); curl_easy_setopt(curl, CURLOPT_CURLU, urlp); res = curl_easy_perform(curl); curl_url_cleanup(urlp); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.63.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_URL (3), .BR curl_url (3), .BR curl_url_cleanup (3), .BR curl_url_dup (3), .BR curl_url_get (3), .BR curl_url_set (3), .BR curl_url_strerror (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_CUSTOMREQUEST.3 .\" generated by cd2nroff 0.1 from CURLOPT_CUSTOMREQUEST.md .TH CURLOPT_CUSTOMREQUEST 3 "2025-06-27" libcurl .SH NAME CURLOPT_CUSTOMREQUEST \- custom request method .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_CUSTOMREQUEST, char method); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. When changing the request \fImethod\fP by setting \fICURLOPT_CUSTOMREQUEST(3)\fP, you do not actually change how libcurl behaves or acts: you only change the actual string sent in the request. libcurl passes on the verbatim string in its request without any filter or other safe guards. That includes white space and control characters. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Restore to the internal default by setting this to NULL. This option can be used to specify the request: .IP HTTP Instead of GET or HEAD when performing HTTP based requests. This is particularly useful, for example, for performing an HTTP DELETE request. For example: When you tell libcurl to do a HEAD request, but then specify a GET though a custom request libcurl still acts as if it sent a HEAD. To switch to a proper HEAD use \fICURLOPT_NOBODY(3)\fP, to switch to a proper POST use \fICURLOPT_POST(3)\fP or \fICURLOPT_POSTFIELDS(3)\fP and to switch to a proper GET use \fICURLOPT_HTTPGET(3)\fP. Many people have wrongly used this option to replace the entire request with their own, including multiple headers and POST contents. While that might work in many cases, it might cause libcurl to send invalid requests and it could possibly confuse the remote server badly. Use \fICURLOPT_POST(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP to set POST data. Use \fICURLOPT_HTTPHEADER(3)\fP to replace or extend the set of headers sent by libcurl. Use \fICURLOPT_HTTP_VERSION(3)\fP to change the HTTP version. When this option is used together with \fICURLOPT_FOLLOWLOCATION(3)\fP, the custom set method overrides the method libcurl could otherwise change to for the subsequent requests. You can fine\-tune that decision by using the CURLFOLLOW_OBEYCODE bit to \fICURLOPT_FOLLOWLOCATION(3)\fP to make redirects adhere to the redirect response code as the protocol instructs. .IP FTP Instead of LIST and NLST when performing FTP directory listings. .IP IMAP Instead of LIST when issuing IMAP based requests. .IP POP3 Instead of LIST and RETR when issuing POP3 based requests. For example: When you tell libcurl to use a custom request it behaves like a LIST or RETR command was sent where it expects data to be returned by the server. As such \fICURLOPT_NOBODY(3)\fP should be used when specifying commands such as \fBDELE\fP and \fBNOOP\fP for example. .IP SMTP Instead of a \fBHELP\fP or \fBVRFY\fP when issuing SMTP based requests. For example: Normally a multi line response is returned which can be used, in conjunction with \fICURLOPT_MAIL_RCPT(3)\fP, to specify an EXPN request. If the \fICURLOPT_NOBODY(3)\fP option is specified then the request can be used to issue \fBNOOP\fP and \fBRSET\fP commands. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp, http, imap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); / DELETE the given path */ curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_EFFECTIVE_METHOD (3), .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_NOBODY (3), .BR CURLOPT_REQUEST_TARGET (3)	3.88 KB	2025-07-08 09:41
📄 CURLOPT_DEBUGDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_DEBUGDATA.md .TH CURLOPT_DEBUGDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_DEBUGDATA \- pointer passed to the debug callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DEBUGDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP to whatever you want passed in to your \fICURLOPT_DEBUGFUNCTION(3)\fP in the last void * argument. This pointer is not used by libcurl, it is only passed to the callback. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct data { void custom; }; static int my_trace(CURL handle, curl_infotype type, char data, size_t size, void clientp) { struct data mine = clientp; printf("our ptr: %p\\n", mine->custom); / output debug info / return 0; } int main(void) { CURL curl; CURLcode res; struct data my_tracedata; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); curl_easy_setopt(curl, CURLOPT_DEBUGDATA, &my_tracedata); /* the DEBUGFUNCTION has no effect until we enable VERBOSE / curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); / always cleanup */ curl_easy_cleanup(curl); } return 0; } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3)	1.67 KB	2025-07-08 09:41
📄 CURLOPT_DEBUGFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_DEBUGFUNCTION.md .TH CURLOPT_DEBUGFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_DEBUGFUNCTION \- debug callback .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLINFO_TEXT = 0, CURLINFO_HEADER_IN, /* 1 / CURLINFO_HEADER_OUT, / 2 / CURLINFO_DATA_IN, / 3 / CURLINFO_DATA_OUT, / 4 / CURLINFO_SSL_DATA_IN, / 5 / CURLINFO_SSL_DATA_OUT, / 6 / CURLINFO_END } curl_infotype; int debug_callback(CURL handle, curl_infotype type, char data, size_t size, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_DEBUGFUNCTION, debug_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. \fICURLOPT_DEBUGFUNCTION(3)\fP replaces the standard debug function used when \fICURLOPT_VERBOSE(3)\fP is in effect. This callback receives debug information, as specified in the \fItype\fP argument. This function must return 0. The \fIdata\fP pointed to by the char passed to this function is not null\-terminated, but is exactly of the \fIsize\fP as told by the \fIsize\fP argument. \fBWARNING\fP this callback may receive sensitive contents from headers and data, including information sent as \fBCURLINFO_TEXT\fP. The \fIclientp\fP argument is the pointer set with \fICURLOPT_DEBUGDATA(3)\fP. Available \fBcurl_infotype\fP values: .IP CURLINFO_TEXT The data is informational text. .IP CURLINFO_HEADER_IN The data is header (or header\-like) data received from the peer. .IP CURLINFO_HEADER_OUT The data is header (or header\-like) data sent to the peer. .IP CURLINFO_DATA_IN The data is the unprocessed protocol data received from the peer. Even if the data is encoded or compressed, it is not provided decoded nor decompressed to this callback. If you need the data in decoded and decompressed form, use \fICURLOPT_WRITEFUNCTION(3)\fP. .IP CURLINFO_DATA_OUT The data is protocol data sent to the peer. .IP CURLINFO_SSL_DATA_OUT The data is SSL/TLS (binary) data sent to the peer. .IP CURLINFO_SSL_DATA_IN The data is SSL/TLS (binary) data received from the peer. .PP WARNING: This callback may be called with the curl \fIhandle\fP set to an internal handle. (Added in 8.4.0) If you need to distinguish your curl \fIhandle\fP from internal handles then set \fICURLOPT_PRIVATE(3)\fP on your handle. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static void dump(const char text, FILE stream, unsigned char ptr, size_t size) { size_t i; size_t c; unsigned int width = 0x10; fprintf(stream, "%s, %10.10ld bytes (0x%8.8lx)\\n", text, (long)size, (long)size); for(i = 0; i < size; i += width) { fprintf(stream, "%4.4lx: ", (long)i); / show hex to the left / for(c = 0; c < width; c++) { if(i + c < size) fprintf(stream, "%02x ", ptr[i + c]); else fputs(" ", stream); } / show data on the right / for(c = 0; (c < width) && (i + c < size); c++) { char x = (ptr[i + c] >= 0x20 && ptr[i + c] < 0x80) ? ptr[i + c] : '.'; fputc(x, stream); } fputc('\\n', stream); / newline / } } static int my_trace(CURL handle, curl_infotype type, char data, size_t size, void clientp) { const char text; (void)handle; / prevent compiler warning / (void)clientp; switch(type) { case CURLINFO_TEXT: fputs("== Info: ", stderr); fwrite(data, size, 1, stderr); default: / in case a new one is introduced to shock us / return 0; case CURLINFO_HEADER_OUT: text = "=> Send header"; break; case CURLINFO_DATA_OUT: text = "=> Send data"; break; case CURLINFO_SSL_DATA_OUT: text = "=> Send SSL data"; break; case CURLINFO_HEADER_IN: text = "<= Recv header"; break; case CURLINFO_DATA_IN: text = "<= Recv data"; break; case CURLINFO_SSL_DATA_IN: text = "<= Recv SSL data"; break; } dump(text, stderr, (unsigned char )data, size); return 0; } int main(void) { CURL curl; CURLcode res; curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_DEBUGFUNCTION, my_trace); / the DEBUGFUNCTION has no effect until we enable VERBOSE / curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); / example.com is redirected, so we tell libcurl to follow redirection / curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); res = curl_easy_perform(curl); / Check for errors / if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\\n", curl_easy_strerror(res)); / always cleanup */ curl_easy_cleanup(curl); } return 0; } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONN_ID (3), .BR CURLINFO_XFER_ID (3), .BR CURLOPT_DEBUGDATA (3), .BR CURLOPT_VERBOSE (3), .BR curl_global_trace (3)	5.15 KB	2025-07-08 09:41
📄 CURLOPT_DEFAULT_PROTOCOL.3 .\" generated by cd2nroff 0.1 from CURLOPT_DEFAULT_PROTOCOL.md .TH CURLOPT_DEFAULT_PROTOCOL 3 "2025-06-27" libcurl .SH NAME CURLOPT_DEFAULT_PROTOCOL \- default protocol to use if the URL is missing a scheme name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DEFAULT_PROTOCOL, char protocol); .fi .SH DESCRIPTION This option tells libcurl to use \fIprotocol\fP if the URL is missing a scheme name. Use one of these protocol (scheme) names: dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp An unknown or unsupported protocol causes error \fICURLE_UNSUPPORTED_PROTOCOL\fP when libcurl parses a URL without a scheme. Parsing happens when \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP is called. The protocol set supported by libcurl vary depending on how it was built. Use \fIcurl_version_info(3)\fP if you need a list of protocol names supported by the build of libcurl that you are using. This option does not change the default proxy protocol (http). Without this option libcurl would make a guess based on the host, see \fICURLOPT_URL(3)\fP for details. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL (make a guess based on the host) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { / set a URL without a scheme / curl_easy_setopt(curl, CURLOPT_URL, "example.com"); / set the default protocol (scheme) for schemeless URLs / curl_easy_setopt(curl, CURLOPT_DEFAULT_PROTOCOL, "https"); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.45.0 .SH RETURN VALUE CURLE_OK if the option is supported. CURLE_OUT_OF_MEMORY if there was insufficient heap space. CURLE_UNKNOWN_OPTION if the option is not supported. .SH SEE ALSO .BR CURLINFO_PROTOCOL (3), .BR CURLINFO_SCHEME (3), .BR CURLOPT_URL (3)	2.17 KB	2025-07-08 09:41
📄 CURLOPT_DIRLISTONLY.3 .\" generated by cd2nroff 0.1 from CURLOPT_DIRLISTONLY.md .TH CURLOPT_DIRLISTONLY 3 "2025-06-27" libcurl .SH NAME CURLOPT_DIRLISTONLY \- ask for names only in a directory listing .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DIRLISTONLY, long listonly); .fi .SH DESCRIPTION For FTP and SFTP based URLs a parameter set to 1 tells the library to list the names of files in a directory, rather than performing a full directory listing that would normally include file sizes, dates etc. For POP3 a parameter of 1 tells the library to list the email message or messages on the POP3 server. This can be used to change the default behavior of libcurl, when combined with a URL that contains a message ID, to perform a \&"scan listing" which can then be used to determine the size of an email. For FILE, this option has no effect yet as directories are always listed in this mode. Note: For FTP this causes a NLST command to be sent to the FTP server. Beware that some FTP servers list only files in their response to NLST; they might not include subdirectories and symbolic links. Setting this option to 1 also implies a directory listing even if the URL does not end with a slash, which otherwise is necessary. Do not use this option if you also use \fICURLOPT_WILDCARDMATCH(3)\fP as it effectively breaks that feature. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects ftp, pop3 and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/"); /* list only */ curl_easy_setopt(curl, CURLOPT_DIRLISTONLY, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option was known as CURLOPT_FTPLISTONLY up to 7.16.4. POP3 is supported since 7.21.5. .SH AVAILABILITY Added in curl 7.17.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_WILDCARDMATCH (3)	2.12 KB	2025-07-08 09:41
📄 CURLOPT_DISALLOW_USERNAME_IN_URL.3 .\" generated by cd2nroff 0.1 from CURLOPT_DISALLOW_USERNAME_IN_URL.md .TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "2025-06-27" libcurl .SH NAME CURLOPT_DISALLOW_USERNAME_IN_URL \- disallow specifying username in the URL .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DISALLOW_USERNAME_IN_URL, long disallow); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to not allow URLs that include a username. This is the equivalent to the \fICURLU_DISALLOW_USER\fP flag for the \fIcurl_url_set(3)\fP function. .SH DEFAULT 0 (disabled) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DISALLOW_USERNAME_IN_URL, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. \fIcurl_easy_perform(3)\fP returns CURLE_LOGIN_DENIED if this option is enabled and a URL containing a username is specified. .SH SEE ALSO .BR CURLOPT_PROTOCOLS_STR (3), .BR CURLOPT_URL (3), .BR curl_url_set (3), .BR libcurl-security (3)	1.36 KB	2025-07-08 09:41
📄 CURLOPT_DNS_CACHE_TIMEOUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_CACHE_TIMEOUT.md .TH CURLOPT_DNS_CACHE_TIMEOUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_CACHE_TIMEOUT \- life\-time for DNS cache entries .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_CACHE_TIMEOUT, long age); .fi .SH DESCRIPTION Pass a long, this sets the timeout in seconds. Name resolve results are kept in memory and used for this number of seconds. Set to zero to completely disable caching, or set to \-1 to make the cached entries remain forever. By default, libcurl caches this info for 60 seconds. We recommend users not to tamper with this option unless strictly necessary. If you do, be careful of using large values that can make the cache size grow significantly if many different hostnames are used within that timeout period. The name resolve functions of various libc implementations do not re\-read name server information unless explicitly told so (for example, by calling \fIres_init(3)\fP). This may cause libcurl to keep using the older server even if DHCP has updated the server info, and this may look like a DNS cache issue to the casual libcurl\-app user. DNS entries have a "TTL" property but libcurl does not use that. This DNS cache timeout is entirely speculative that a name resolves to the same address for a small amount of time into the future. Since version 8.1.0, libcurl prunes entries from the DNS cache if it exceeds 30,000 entries no matter which timeout value is used. .SH DEFAULT 60 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* only reuse addresses for a short time / curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L); res = curl_easy_perform(curl); / in this second request, the cache is not be used if more than two seconds have passed since the previous name resolve */ res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT_MS (3), .BR CURLOPT_DNS_SERVERS (3), .BR CURLOPT_DNS_USE_GLOBAL_CACHE (3), .BR CURLOPT_MAXAGE_CONN (3), .BR CURLOPT_RESOLVE (3)	2.46 KB	2025-07-08 09:41
📄 CURLOPT_DNS_INTERFACE.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_INTERFACE.md .TH CURLOPT_DNS_INTERFACE 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_INTERFACE \- interface to speak DNS over .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_INTERFACE, char ifname); .fi .SH DESCRIPTION Pass a char pointer as parameter. Set the name of the network interface that the DNS resolver should bind to. This must be an interface name (not an address). Set this option to NULL to use the default setting (do not bind to a specific interface). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_DNS_INTERFACE, "eth0"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES This option requires that libcurl was built with a resolver backend that supports this operation. The c\-ares backend is the only such one. .SH AVAILABILITY Added in curl 7.33.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_LOCAL_IP4 (3), .BR CURLOPT_DNS_LOCAL_IP6 (3), .BR CURLOPT_DNS_SERVERS (3), .BR CURLOPT_INTERFACE (3)	1.63 KB	2025-07-08 09:41
📄 CURLOPT_DNS_LOCAL_IP4.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_LOCAL_IP4.md .TH CURLOPT_DNS_LOCAL_IP4 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_LOCAL_IP4 \- IPv4 address to bind DNS resolves to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_LOCAL_IP4, char address); .fi .SH DESCRIPTION Set the local IPv4 \fIaddress\fP that the resolver should bind to. The argument should be of type char * and contain a single numerical IPv4 address as a string. Set this option to NULL to use the default setting (do not bind to a specific IP address). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP4, "192.168.0.14"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES This option requires that libcurl was built with a resolver backend that supports this operation. The c\-ares backend is the only such one. .SH AVAILABILITY Added in curl 7.33.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_INTERFACE (3), .BR CURLOPT_DNS_LOCAL_IP6 (3), .BR CURLOPT_DNS_SERVERS (3)	1.63 KB	2025-07-08 09:41
📄 CURLOPT_DNS_LOCAL_IP6.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_LOCAL_IP6.md .TH CURLOPT_DNS_LOCAL_IP6 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_LOCAL_IP6 \- IPv6 address to bind DNS resolves to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_LOCAL_IP6, char address); .fi .SH DESCRIPTION Set the local IPv6 \fIaddress\fP that the resolver should bind to. The argument should be of type char * and contain a single IPv6 address as a string. Set this option to NULL to use the default setting (do not bind to a specific IP address). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_DNS_LOCAL_IP6, "fe80::a9ff:fe46:b619"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES This option requires that libcurl was built with a resolver backend that supports this operation. The c\-ares backend is the only such one. .SH AVAILABILITY Added in curl 7.33.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_INTERFACE (3), .BR CURLOPT_DNS_LOCAL_IP4 (3), .BR CURLOPT_DNS_SERVERS (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_DNS_SERVERS.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_SERVERS.md .TH CURLOPT_DNS_SERVERS 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_SERVERS \- DNS servers to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_SERVERS, char servers); .fi .SH DESCRIPTION Pass a char pointer that is the list of DNS servers to be used instead of the system default. The format of the dns servers option is: .nf host[:port][,host[:port]]... .fi For example: .nf 192.168.1.100,192.168.1.101,3.4.5.6 .fi The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_DNS_SERVERS, "192.168.1.100:53,192.168.1.101"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES This option requires that libcurl was built with a resolver backend that supports this operation. The c\-ares backend is the only such one. .SH AVAILABILITY Added in curl 7.24.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_DNS_LOCAL_IP4 (3), .BR CURLOPT_DNS_LOCAL_IP6 (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_DNS_SHUFFLE_ADDRESSES.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_SHUFFLE_ADDRESSES.md .TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_SHUFFLE_ADDRESSES, long onoff); .fi .SH DESCRIPTION Pass a long set to 1 to enable this option. When a name is resolved and more than one IP address is returned, this function shuffles the order of all returned addresses so that they are used in a random order. This is similar to the ordering behavior of the legacy gethostbyname function which is no longer used on most platforms. Addresses are not reshuffled if name resolution is completed using the DNS cache. \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP can be used together with this option to reduce DNS cache timeout or disable caching entirely if frequent reshuffling is needed. Since the addresses returned are randomly reordered, the order is not in accordance with RFC 3484 or any other deterministic order that may be generated by the system\(aqs name resolution implementation. This may have performance impacts and may cause IPv4 to be used before IPv6 or vice versa. .SH DEFAULT 0 (disabled) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DNS_SHUFFLE_ADDRESSES, 1L); curl_easy_perform(curl); /* always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.60.0 .SH RETURN VALUE CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. .SH SEE ALSO .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_IPRESOLVE (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_DNS_USE_GLOBAL_CACHE.3 .\" generated by cd2nroff 0.1 from CURLOPT_DNS_USE_GLOBAL_CACHE.md .TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "2025-06-27" libcurl .SH NAME CURLOPT_DNS_USE_GLOBAL_CACHE \- global DNS cache .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DNS_USE_GLOBAL_CACHE, long enable); .fi .SH DESCRIPTION Has no function since 7.62.0. Do not use. Pass a long. If the \fIenable\fP value is 1, it tells curl to use a global DNS cache that survives between easy handle creations and deletions. This is not thread\-safe and this uses a global variable. See \fICURLOPT_SHARE(3)\fP and \fIcurl_share_init(3)\fP for the correct way to share DNS cache between transfers. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* switch off the use of a global, thread unsafe, cache */ curl_easy_setopt(curl, CURLOPT_DNS_USE_GLOBAL_CACHE, 0L); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH DEPRECATED Deprecated since 7.11.1. Functionality removed in 7.62.0. .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_SHARE (3)	1.49 KB	2025-07-08 09:41
📄 CURLOPT_DOH_SSL_VERIFYHOST.3 .\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYHOST.md .TH CURLOPT_DOH_SSL_VERIFYHOST 3 "2025-06-27" libcurl .SH NAME CURLOPT_DOH_SSL_VERIFYHOST \- verify the hostname in the DoH SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DOH_SSL_VERIFYHOST, long verify); .fi .SH DESCRIPTION Pass a long set to 2L as asking curl to \fIverify\fP the DoH (DNS\-over\-HTTPS) server\(aqs certificate name fields against the hostname. This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYHOST(3)\fP and only affects requests to the DoH server. When \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is 2, the SSL certificate provided by the DoH server must indicate that the server name is the same as the server name to which you meant to connect to, or the connection fails. curl considers the DoH server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the hostname in the DoH URL to which you told curl to connect. When the \fIverify\fP value is set to 1L it is treated the same as 2L. However for consistency with the other \fIVERIFYHOST\fP options we suggest use 2 and not 1. When the \fIverify\fP value is set to 0L, the connection succeeds regardless of the names used in the certificate. Use that ability with caution. See also \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP to verify the digital signature of the DoH server certificate. .SH DEFAULT 2 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query"); /* Disable host name verification of the DoH server */ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYHOST, 0L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.76.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DOH_SSL_VERIFYPEER (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.4 KB	2025-07-08 09:41
📄 CURLOPT_DOH_SSL_VERIFYPEER.3 .\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYPEER.md .TH CURLOPT_DOH_SSL_VERIFYPEER 3 "2025-06-27" libcurl .SH NAME CURLOPT_DOH_SSL_VERIFYPEER \- verify the DoH SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DOH_SSL_VERIFYPEER, long verify); .fi .SH DESCRIPTION Pass a long as parameter set to 1L to enable or 0L to disable. This option tells curl to verify the authenticity of the DoH (DNS\-over\-HTTPS) server\(aqs certificate. A value of 1 means curl verifies; 0 (zero) means it does not. This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYPEER(3)\fP and only affects requests to the DoH server. When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the \fICURLOPT_CAPATH(3)\fP option. When \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to prove that the certificate is authentic, the connection fails. When the option is zero, the peer certificate verification succeeds regardless. Authenticating the certificate is not enough to be sure about the server. You typically also want to ensure that the server is the server you mean to be talking to. Use \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP for that. The check that the hostname in the certificate is valid for the hostname you are connecting to is done independently of the \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP option. WARNING: disabling verification of the certificate allows bad guys to man\-in\-the\-middle the communication without you knowing it. Disabling verification makes the communication insecure. Just having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end\-point. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query"); /* Disable certificate verification of the DoH server */ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYPEER, 0L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.76.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_DOH_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	3.16 KB	2025-07-08 09:41
📄 CURLOPT_DOH_SSL_VERIFYSTATUS.3 .\" generated by cd2nroff 0.1 from CURLOPT_DOH_SSL_VERIFYSTATUS.md .TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "2025-06-27" libcurl .SH NAME CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DoH SSL certificate\(aqs status .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DOH_SSL_VERIFYSTATUS, long verify); .fi .SH DESCRIPTION Pass a long as parameter set to 1 to enable or 0 to disable. This option determines whether libcurl verifies the status of the DoH (DNS\-over\-HTTPS) server cert using the "Certificate Status Request" TLS extension (aka. OCSP stapling). This option is the DoH equivalent of \fICURLOPT_SSL_VERIFYSTATUS(3)\fP and only affects requests to the DoH server. If this option is enabled and the server does not support the TLS extension, the verification fails. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://cloudflare-dns.com/dns-query"); /* Ask for OCSP stapling when verifying the DoH server */ curl_easy_setopt(curl, CURLOPT_DOH_SSL_VERIFYSTATUS, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.76.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DOH_SSL_VERIFYHOST (3), .BR CURLOPT_DOH_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYSTATUS (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_DOH_URL.3 .\" generated by cd2nroff 0.1 from CURLOPT_DOH_URL.md .TH CURLOPT_DOH_URL 3 "2025-06-27" libcurl .SH NAME CURLOPT_DOH_URL \- provide the DNS\-over\-HTTPS URL .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_DOH_URL, char URL); .fi .SH DESCRIPTION Pass in a pointer to a \fIURL\fP for the DoH server to use for name resolving. The parameter should be a char pointer to a null\-terminated string which must be a valid and correct HTTPS URL. libcurl does not validate the syntax or use this variable until the transfer is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still returns \fICURLE_OK\fP. curl sends POST requests to the given DNS\-over\-HTTPS URL. To find the DoH server itself, which might be specified using a name, libcurl uses the default name lookup function. You can bootstrap that by providing the address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH INHERIT OPTIONS DoH lookups use SSL and some SSL settings from your transfer are inherited, like \fICURLOPT_SSL_CTX_FUNCTION(3)\fP. The hostname and peer certificate verification settings are not inherited but can be controlled separately via \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited. .SH KNOWN BUGS Even when DoH is set to be used with this option, there are still some name resolves that are performed without it, using the default name resolver mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP, \fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or \fBCURLPROXY_SOCKS5\fP and probably some more. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so when given a bad DoH URL, libcurl might not detect the problem until it later tries to resolve a name with it. .SH SEE ALSO .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_RESOLVE (3), .BR CURLOPT_VERBOSE (3)	2.7 KB	2025-07-08 09:41
📄 CURLOPT_ECH.3 .\" generated by cd2nroff 0.1 from CURLOPT_ECH.md .TH CURLOPT_ECH 3 "2025-06-27" libcurl .SH NAME CURLOPT_ECH \- configuration for Encrypted Client Hello .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ECH, char config); .fi .SH DESCRIPTION ECH is only compatible with TLSv1.3. This experimental feature requires a special build of OpenSSL, as ECH is not yet supported in OpenSSL releases. In contrast ECH is supported by the latest BoringSSL, wolfSSL and rustls\-ffi releases. There is also a known issue with using wolfSSL which does not support ECH when the HelloRetryRequest mechanism is used. Pass a string that specifies configuration details for ECH. In all cases, if ECH is attempted, it may fail for various reasons. The keywords supported are: .IP false Turns off ECH. .IP grease Instructs client to emit a GREASE ECH extension. (The connection fails if ECH is attempted but fails.) .IP true Instructs client to attempt ECH, if possible, but to not fail if attempting ECH is not possible. .IP hard Instructs client to attempt ECH and fail if attempting ECH is not possible. .IP ecl:\<base64-value\> If the string starts with \fIecl:\fP then the remainder of the string should be a base64\-encoded ECHConfigList that is used for ECH rather than attempting to download such a value from the DNS. .IP pn:\<name\> If the string starts with \fIpn:\fP then the remainder of the string should be a DNS/hostname that is used to over\-ride the public_name field of the ECHConfigList that is used for ECH. .PP The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL or "false" to disable its use again. .SH DEFAULT NULL, meaning ECH is disabled. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, rustls and wolfSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); const char config = \\ "ecl:AED+DQA87wAgACB/RuzUCsW3uBbSFI7mzD63TUXpI8sGDTnFTbFCDpa+" \\ "CAAEAAEAAQANY292ZXIuZGVmby5pZQAA"; if(curl) { curl_easy_setopt(curl, CURLOPT_ECH, config); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 8.8.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DOH_URL (3)	2.52 KB	2025-07-08 09:41
📄 CURLOPT_EGDSOCKET.3 .\" generated by cd2nroff 0.1 from CURLOPT_EGDSOCKET.md .TH CURLOPT_EGDSOCKET 3 "2025-06-27" libcurl .SH NAME CURLOPT_EGDSOCKET \- EGD socket path .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_EGDSOCKET, char path); .fi .SH DESCRIPTION Deprecated option. It serves no purpose anymore. .SH DEFAULT NULL .SH DEPRECATED This option was deprecated in 7.84.0. .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_RANDOM_FILE (3)	670 B	2025-07-08 09:41
📄 CURLOPT_ERRORBUFFER.3 .\" generated by cd2nroff 0.1 from CURLOPT_ERRORBUFFER.md .TH CURLOPT_ERRORBUFFER 3 "2025-06-27" libcurl .SH NAME CURLOPT_ERRORBUFFER \- error buffer for error messages .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ERRORBUFFER, char buf); .fi .SH DESCRIPTION Pass a char pointer to a buffer that libcurl may use to store human readable error messages on failures or problems. This may be more helpful than just the return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer must be at least \fBCURL_ERROR_SIZE\fP bytes big. You must keep the associated buffer available until libcurl no longer needs it. Failing to do so might cause odd behavior or even crashes. libcurl might need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same option again to use a different pointer. Do not rely on the contents of the buffer unless an error code was returned. Since 7.60.0 libcurl initializes the contents of the error buffer to an empty string before performing the transfer. For earlier versions if an error code was returned but there was no error detail then the buffer was untouched. Do not attempt to set the contents of the buffer yourself, including in any callbacks you write that may be called by libcurl. The library may overwrite the buffer after your callback returns. Consider \fICURLOPT_VERBOSE(3)\fP and \fICURLOPT_DEBUGFUNCTION(3)\fP to better debug and trace why errors happen. Using this option multiple times makes the last set pointer override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <string.h> /* for strlen() / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; char errbuf[CURL_ERROR_SIZE]; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* provide a buffer to store errors in / curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf); / set the error buffer as empty before performing a request / errbuf[0] = 0; / perform the request / res = curl_easy_perform(curl); / if the request did not complete correctly, show the error information. if no detailed error information was written to errbuf show the more generic information from curl_easy_strerror instead. */ if(res != CURLE_OK) { size_t len = strlen(errbuf); fprintf(stderr, "\\nlibcurl: (%d) ", res); if(len) fprintf(stderr, "%s%s", errbuf, ((errbuf[len - 1] != '\\n') ? "\\n" : "")); else fprintf(stderr, "%s\\n", curl_easy_strerror(res)); } } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_VERBOSE (3), .BR curl_easy_strerror (3), .BR curl_multi_strerror (3), .BR curl_share_strerror (3), .BR curl_url_strerror (3)	3.04 KB	2025-07-08 09:41
📄 CURLOPT_EXPECT_100_TIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_EXPECT_100_TIMEOUT_MS.md .TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100\-continue response .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_EXPECT_100_TIMEOUT_MS, long milliseconds); .fi .SH DESCRIPTION Pass a long to tell libcurl the number of \fImilliseconds\fP to wait for a server response with the HTTP status 100 (Continue), 417 (Expectation Failed) or similar after sending an HTTP request containing an Expect: 100\-continue header. If this times out before a response is received, the request body is sent anyway. .SH DEFAULT 1000 milliseconds .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* wait 3 seconds for 100-continue */ curl_easy_setopt(curl, CURLOPT_EXPECT_100_TIMEOUT_MS, 3000L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.36.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPOST (3), .BR CURLOPT_POST (3)	1.34 KB	2025-07-08 09:41
📄 CURLOPT_FAILONERROR.3 .\" generated by cd2nroff 0.1 from CURLOPT_FAILONERROR.md .TH CURLOPT_FAILONERROR 3 "2025-06-27" libcurl .SH NAME CURLOPT_FAILONERROR \- request failure on HTTP response >= 400 .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FAILONERROR, long fail); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to fail the request if the HTTP code returned is equal to or larger than 400. The default action would be to return the page normally, ignoring that code. This method is not fail\-safe and there are occasions where non\-successful response codes slip through, especially when authentication is involved (response codes 401 and 407). You might get some amounts of headers transferred before this situation is detected, like when a "100\-continue" is received as a response to a POST/PUT and a 401 or 407 is received immediately afterwards. When this option is used and an error is detected, it causes the connection to get closed and \fICURLE_HTTP_RETURNED_ERROR\fP is returned. .SH DEFAULT 0, do not fail on error .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_FAILONERROR, 1L); ret = curl_easy_perform(curl); if(ret == CURLE_HTTP_RETURNED_ERROR) { /* an HTTP response error problem */ } } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR CURLOPT_HTTP200ALIASES (3), .BR CURLOPT_KEEP_SENDING_ON_ERROR (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_FILETIME.3 .\" generated by cd2nroff 0.1 from CURLOPT_FILETIME.md .TH CURLOPT_FILETIME 3 "2025-06-27" libcurl .SH NAME CURLOPT_FILETIME \- get the modification time of the remote resource .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FILETIME, long gettime); .fi .SH DESCRIPTION Pass a long. If it is 1, libcurl attempts to get the modification time of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The \fIcurl_easy_getinfo(3)\fP function with the \fICURLINFO_FILETIME(3)\fP argument can be used after a transfer to extract the received time (if any). .SH DEFAULT 0 .SH PROTOCOLS This functionality affects file, ftp, http, sftp and smb .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/path.html"); /* Ask for filetime / curl_easy_setopt(curl, CURLOPT_FILETIME, 1L); res = curl_easy_perform(curl); if(CURLE_OK == res) { long filetime; res = curl_easy_getinfo(curl, CURLINFO_FILETIME, &filetime); if((CURLE_OK == res) && (filetime >= 0)) { time_t file_time = (time_t)filetime; printf("filetime: %s", ctime(&file_time)); } } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_FILETIME (3), .BR curl_easy_getinfo (3)	1.63 KB	2025-07-08 09:41
📄 CURLOPT_FNMATCH_DATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_FNMATCH_DATA.md .TH CURLOPT_FNMATCH_DATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FNMATCH_DATA, void pointer); .fi .SH DESCRIPTION Pass a pointer that is untouched by libcurl and passed as the ptr argument to the \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf extern int string_match(const char s1, const char s2); struct local_stuff { void custom; }; static int my_fnmatch(void clientp, const char pattern, const char string) { struct local_stuff my = clientp; printf("my ptr: %p\\n", my->custom); if(string_match(pattern, string)) return CURL_FNMATCHFUNC_MATCH; else return CURL_FNMATCHFUNC_NOMATCH; } int main(void) { struct local_stuff local_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FNMATCH_FUNCTION (3), .BR CURLOPT_WILDCARDMATCH (3)	1.6 KB	2025-07-08 09:41
📄 CURLOPT_FNMATCH_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_FNMATCH_FUNCTION.md .TH CURLOPT_FNMATCH_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_FNMATCH_FUNCTION \- wildcard match callback .SH SYNOPSIS .nf #include <curl/curl.h> int fnmatch_callback(void ptr, const char pattern, const char string); CURLcode curl_easy_setopt(CURL handle, CURLOPT_FNMATCH_FUNCTION, fnmatch_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback is used for wildcard matching. Return \fICURL_FNMATCHFUNC_MATCH\fP if pattern matches the string, \fICURL_FNMATCHFUNC_NOMATCH\fP if not or \fICURL_FNMATCHFUNC_FAIL\fP if an error occurred. .SH DEFAULT NULL == an internal function for wildcard matching. .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf extern int string_match(const char s1, const char s2); struct local_stuff { void custom; }; static int my_fnmatch(void clientp, const char pattern, const char string) { struct local_stuff data = clientp; printf("my pointer: %p\\n", data->custom); if(string_match(pattern, string)) return CURL_FNMATCHFUNC_MATCH; else return CURL_FNMATCHFUNC_NOMATCH; } int main(void) { struct local_stuff local_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://ftp.example.com/file*"); curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); curl_easy_setopt(curl, CURLOPT_FNMATCH_FUNCTION, my_fnmatch); curl_easy_setopt(curl, CURLOPT_FNMATCH_DATA, &local_data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_FNMATCH_DATA (3), .BR CURLOPT_WILDCARDMATCH (3)	1.97 KB	2025-07-08 09:41
📄 CURLOPT_FOLLOWLOCATION.3 .\" generated by cd2nroff 0.1 from CURLOPT_FOLLOWLOCATION.md .TH CURLOPT_FOLLOWLOCATION 3 "2025-06-27" libcurl .SH NAME CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FOLLOWLOCATION, long mode); .fi .SH DESCRIPTION This option tells the library to follow \fILocation:\fP header redirects that an HTTP server sends in a 30x response. The \fILocation:\fP header can specify a relative or an absolute URL to follow. The long parameter \fImode\fP instructs how libcurl should act on subsequent requests. \fImode\fP only had a single value (1L) for a long time that enables redirect following. Since 8.13.0, two additional modes are also supported. See below. When following redirects, libcurl issues another request for the new URL and follows subsequent new \fILocation:\fP redirects all the way until no more such headers are returned or the maximum limit is reached. \fICURLOPT_MAXREDIRS(3)\fP is used to limit the number of redirects libcurl follows. libcurl restricts what protocols it automatically follow redirects to. The accepted target protocols are set with \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects. When following a redirect, the specific 30x response code also dictates which request method libcurl uses in the subsequent request: For 301, 302 and 303 responses libcurl switches method from POST to GET unless \fICURLOPT_POSTREDIR(3)\fP instructs libcurl otherwise. All other redirect response codes make libcurl use the same method again. When libcurl switches method to GET, it then uses that method without sending any request body. If it does not change the method, it sends the subsequent request the same way as the previous one; including the request body if one was provided. For users who think the existing location following is too naive, too simple or just lacks features, it is easy to instead implement your own redirect follow logic with the use of \fIcurl_easy_getinfo(3)\fP\(aqs \fICURLINFO_REDIRECT_URL(3)\fP option instead of using \fICURLOPT_FOLLOWLOCATION(3)\fP. By default, libcurl only sends \fIAuthentication:\fP or explicitly set \fICookie:\fP headers to the initial host given in the original URL, to avoid leaking username + password to other sites. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP is provided to change that behavior. Due to the way HTTP works, almost any header can be made to contain data a client may not want to pass on to other servers than the initially intended host and for all other headers than the two mentioned above, there is no protection from this happening when libcurl is told to follow redirects. Pick one of the following modes: .IP "CURLFOLLOW_ALL (1)" Before 8.13.0 this bit had no name and 1L was just the value to enable this option. This makes a set custom method be used in all HTTP requests, even after redirects. .IP "CURLFOLLOW_OBEYCODE (2)" When there is a custom request method set with \fICURLOPT_CUSTOMREQUEST(3)\fP, that set method replaces what libcurl would otherwise use. If a 301/302/303 response code is returned to signal a redirect, the method is changed from POST to \fIGET\fP. For 307/308, the custom method remains set and used. Note that only POST (or a custom post) is changed to GET on 301/302, its not change PUT etc \- and therefore also not when libcurl issues a custom PUT. A 303 response makes it switch to GET independently of the original method (except for HEAD). To control for which of the 301/302/303 status codes libcurl should \fInot\fP switch back to GET for when doing a custom POST, and instead keep the custom method, use \fICURLOPT_POSTREDIR(3)\fP. If you prefer a custom POST method to be reset to exactly the method \fIPOST\fP, use CURLFOLLOW_FIRSTONLY instead. .IP "CURLFOLLOW_FIRSTONLY (3)" When there is a custom request method set with \fICURLOPT_CUSTOMREQUEST(3)\fP, that set method replaces what libcurl would otherwise use in the first outgoing request only. The second request is then done according to the redirect response code. If you prefer your custom method to remain in use after a 307/308 redirect, use CURLFOLLOW_OBEYCODE instead. .PP .SH NOTE Since libcurl changes method or not based on the specific HTTP response code, setting \fICURLOPT_CUSTOMREQUEST(3)\fP while following redirects may change what libcurl would otherwise do and if not that carefully may even make it misbehave since \fICURLOPT_CUSTOMREQUEST(3)\fP overrides the method libcurl would otherwise select internally. Setting the CURLFOLLOW_OBEYCODE bit makes libcurl \fInot\fP use the custom set method after redirects for 301, 302 and 303 responses. Unless the \fICURLOPT_POSTREDIR(3)\fP bits are set for those status codes. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* example.com is redirected, so we tell libcurl to follow redirection */ curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLINFO_REDIRECT_URL (3), .BR CURLOPT_POSTREDIR (3), .BR CURLOPT_PROTOCOLS_STR (3), .BR CURLOPT_REDIR_PROTOCOLS_STR (3), .BR CURLOPT_UNRESTRICTED_AUTH (3)	5.48 KB	2025-07-08 09:41
📄 CURLOPT_FORBID_REUSE.3 .\" generated by cd2nroff 0.1 from CURLOPT_FORBID_REUSE.md .TH CURLOPT_FORBID_REUSE 3 "2025-06-27" libcurl .SH NAME CURLOPT_FORBID_REUSE \- make connection get closed at once after use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FORBID_REUSE, long close); .fi .SH DESCRIPTION Pass a long. Set \fIclose\fP to 1 to make libcurl explicitly close the connection when done with the transfer. Normally, libcurl keeps all connections alive when done with one transfer in case a succeeding one follows that can reuse them. This option should be used with caution and only if you understand what it does as it can seriously impact performance. Set to 0 to have libcurl keep the connection open for possible later reuse (default behavior). .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_FORBID_REUSE, 1L); curl_easy_perform(curl); /* this second transfer may not reuse the same connection */ curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FRESH_CONNECT (3), .BR CURLOPT_MAXCONNECTS (3), .BR CURLOPT_MAXLIFETIME_CONN (3)	1.52 KB	2025-07-08 09:41
📄 CURLOPT_FRESH_CONNECT.3 .\" generated by cd2nroff 0.1 from CURLOPT_FRESH_CONNECT.md .TH CURLOPT_FRESH_CONNECT 3 "2025-06-27" libcurl .SH NAME CURLOPT_FRESH_CONNECT \- force a new connection to be used .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FRESH_CONNECT, long fresh); .fi .SH DESCRIPTION Pass a long. Set to 1 to make the next transfer use a new (fresh) connection by force instead of trying to reuse an existing one. This option should be used with caution and only if you understand what it does as it may impact performance negatively. Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the connection is closed after use so that it cannot be reused. Set \fIfresh\fP to 0 to have libcurl attempt reusing an existing connection (default behavior). .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_FRESH_CONNECT, 1L); /* this transfer must use a new connection, not reuse an existing */ curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FORBID_REUSE (3), .BR CURLOPT_MAXAGE_CONN (3), .BR CURLOPT_MAXLIFETIME_CONN (3)	1.52 KB	2025-07-08 09:41
📄 CURLOPT_FTPPORT.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTPPORT.md .TH CURLOPT_FTPPORT 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTPPORT \- make FTP transfer active .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTPPORT, char spec); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It specifies that the FTP transfer should be made actively and the given string is used to get the IP address to use for the FTP PORT instruction. The PORT instruction tells the remote server to do a TCP connect to our specified IP address. The string may be a plain IP address, a hostname, a network interface name (under Unix) or just a \(aq\-\(aq symbol to let the library use your system\(aqs default IP address. Default FTP operations are passive, and does not use the PORT command. The address can be followed by a \(aq:\(aq to specify a port, optionally followed by a \(aq\-\(aq to specify a port range. If the port specified is 0, the operating system picks a free port. If a range is provided and all ports in the range are not available, libcurl reports CURLE_FTP_PORT_FAILED for the handle. Invalid port/range settings are ignored. IPv6 addresses followed by a port or port range have to be in brackets. IPv6 addresses without port/range specifier can be in brackets. Examples with specified ports: .nf eth0:0 192.168.1.2:32000-33000 curl.se:32123 [::1]:1234-4567 .fi We strongly advise against specifying the address with a name, as it causes libcurl to do a blocking name resolve call to retrieve the IP address. That name resolve operation does \fBnot\fP use DNS\-over\-HTTPS even if \fICURLOPT_DOH_URL(3)\fP is set. Using anything else than "\-" for this option should typically only be done if you have special knowledge and confirmation that it works. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. You disable PORT again and go back to using the passive version by setting this option to NULL. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt"); curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_USE_EPRT (3), .BR CURLOPT_FTP_USE_EPSV (3)	2.71 KB	2025-07-08 09:41
📄 CURLOPT_FTPSSLAUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTPSSLAUTH.md .TH CURLOPT_FTPSSLAUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTPSSLAUTH \- order in which to attempt TLS vs SSL .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTPSSLAUTH, long order); .fi .SH DESCRIPTION Pass a long using one of the values from below, to alter how libcurl issues \&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only interesting if \fICURLOPT_USE_SSL(3)\fP is also set. Possible \fIorder\fP values: .IP CURLFTPAUTH_DEFAULT Allow libcurl to decide. .IP CURLFTPAUTH_SSL Try "AUTH SSL" first, and only if that fails try "AUTH TLS". .IP CURLFTPAUTH_TLS Try "AUTH TLS" first, and only if that fails try "AUTH SSL". .SH DEFAULT CURLFTPAUTH_DEFAULT .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_TRY); /* funny server, ask for SSL before TLS */ curl_easy_setopt(curl, CURLOPT_FTPSSLAUTH, (long)CURLFTPAUTH_SSL); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.12.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_SSL_CCC (3), .BR CURLOPT_USE_SSL (3)	1.51 KB	2025-07-08 09:41
📄 CURLOPT_FTP_ACCOUNT.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_ACCOUNT.md .TH CURLOPT_FTP_ACCOUNT 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_ACCOUNT \- account info for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_ACCOUNT, char account); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string (or NULL to disable). When an FTP server asks for "account data" after username and password has been provided, this data is sent off using the ACCT command. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_FTP_ACCOUNT, "human-resources"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.13.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PASSWORD (3), .BR CURLOPT_USERNAME (3)	1.35 KB	2025-07-08 09:41
📄 CURLOPT_FTP_ALTERNATIVE_TO_USER.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_ALTERNATIVE_TO_USER.md .TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_ALTERNATIVE_TO_USER, char cmd); .fi .SH DESCRIPTION Pass a char pointer as parameter, pointing to a string which is used to authenticate if the usual FTP "USER user" and "PASS password" negotiation fails. This is currently only known to be required when connecting to Tumbleweed\(aqs Secure Transport FTPS server using client certificates for authentication. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_FTP_ALTERNATIVE_TO_USER, "two users"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_ACCOUNT (3), .BR CURLOPT_FTP_SKIP_PASV_IP (3), .BR CURLOPT_SERVER_RESPONSE_TIMEOUT (3), .BR CURLOPT_USERNAME (3)	1.5 KB	2025-07-08 09:41
📄 CURLOPT_FTP_CREATE_MISSING_DIRS.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_CREATE_MISSING_DIRS.md .TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing directories for FTP and SFTP .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLFTP_CREATE_DIR_NONE, CURLFTP_CREATE_DIR, CURLFTP_CREATE_DIR_RETRY } curl_ftpcreatedir; CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_CREATE_MISSING_DIRS, long create); .fi .SH DESCRIPTION Pass a long telling libcurl to \fIcreate\fP the dir. If the value is \fICURLFTP_CREATE_DIR\fP (1), libcurl may create any remote directory that it fails to "move" into. For FTP requests, that means a CWD command fails. CWD being the command that changes working directory. For SFTP requests, libcurl may create the remote directory if it cannot obtain a handle to the target\-location. The creation fails if a file of the same name as the directory to create already exists or lack of permissions prevents creation. Setting \fIcreate\fP to \fICURLFTP_CREATE_DIR_RETRY\fP (2), tells libcurl to retry the CWD command again if the subsequent \fBMKD\fP command fails. This is especially useful if you are doing many simultaneous connections against the same server and they all have this option enabled, as then CWD may first fail but then another connection does \fBMKD\fP before this connection and thus \fBMKD\fP fails but trying CWD works. .SH DEFAULT CURLFTP_CREATE_DIR_NONE (0) .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/non-existing/new.txt"); curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, (long)CURLFTP_CREATE_DIR_RETRY); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_FILEMETHOD (3), .BR CURLOPT_FTP_USE_EPSV (3)	2.18 KB	2025-07-08 09:41
📄 CURLOPT_FTP_FILEMETHOD.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_FILEMETHOD.md .TH CURLOPT_FTP_FILEMETHOD 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_FILEMETHOD, long method); .fi .SH DESCRIPTION Pass a long telling libcurl which \fImethod\fP to use to reach a file on a FTP(S) server. This option exists because some server implementations are not compliant to what the standards say should work. The argument should be one of the following alternatives: .IP CURLFTPMETHOD_MULTICWD libcurl does a single CWD operation for each path part in the given URL. For deep hierarchies this means many commands. This is how RFC 1738 says it should be done. This is the default but the slowest behavior. .IP CURLFTPMETHOD_NOCWD libcurl makes no CWD at all. libcurl does SIZE, RETR, STOR etc and gives a full path to the server for all these commands. This is the fastest behavior since it skips having to change directories. .IP CURLFTPMETHOD_SINGLECWD libcurl does one CWD with the full target directory and then operates on the file &"normally" (like in the multicwd case). This is somewhat more standards compliant than \(aqnocwd\(aq but without the full penalty of \(aqmulticwd\(aq. .SH DEFAULT CURLFTPMETHOD_MULTICWD .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/1/2/3/4/new.txt"); curl_easy_setopt(curl, CURLOPT_FTP_FILEMETHOD, (long)CURLFTPMETHOD_SINGLECWD); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DIRLISTONLY (3), .BR CURLOPT_FTP_SKIP_PASV_IP (3)	2.04 KB	2025-07-08 09:41
📄 CURLOPT_FTP_SKIP_PASV_IP.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_SKIP_PASV_IP.md .TH CURLOPT_FTP_SKIP_PASV_IP 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_SKIP_PASV_IP \- ignore the IP address in the PASV response .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_SKIP_PASV_IP, long skip); .fi .SH DESCRIPTION Pass a long. If \fIskip\fP is set to 1, it instructs libcurl to not use the IP address the server suggests in its 227\-response to libcurl\(aqs PASV command when libcurl connects the data connection. Instead libcurl reuses the same IP address it already uses for the control connection. It still uses the port number from the 227\-response. This option allows libcurl to work around broken server installations or funny network setups that due to NATs, firewalls or incompetence report the wrong IP address. Setting this option also reduces the risk for various sorts of client abuse by malicious servers. This option has no effect if PORT, EPRT or EPSV is used instead of PASV. .SH DEFAULT 1 since 7.74.0, was 0 before then. .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); /* please ignore the IP in the PASV response */ curl_easy_setopt(curl, CURLOPT_FTP_SKIP_PASV_IP, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTPPORT (3), .BR CURLOPT_FTP_USE_EPRT (3)	1.72 KB	2025-07-08 09:41
📄 CURLOPT_FTP_SSL_CCC.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_SSL_CCC.md .TH CURLOPT_FTP_SSL_CCC 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_SSL_CCC \- switch off SSL again with FTP after auth .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_SSL_CCC, long how); .fi .SH DESCRIPTION If enabled, this option makes libcurl use CCC (Clear Command Channel). It shuts down the SSL/TLS layer after authenticating. The rest of the control channel communication remains unencrypted. This allows NAT routers to follow the FTP transaction. Pass a long using one of the values below .IP CURLFTPSSL_CCC_NONE do not attempt to use CCC. .IP CURLFTPSSL_CCC_PASSIVE Do not initiate the shutdown, but wait for the server to do it. Do not send a reply. .IP CURLFTPSSL_CCC_ACTIVE Initiate the shutdown and wait for a reply. .SH DEFAULT CURLFTPSSL_CCC_NONE .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_USE_SSL, CURLUSESSL_CONTROL); /* go back to clear-text FTP after authenticating */ curl_easy_setopt(curl, CURLOPT_FTP_SSL_CCC, (long)CURLFTPSSL_CCC_ACTIVE); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTPSSLAUTH (3), .BR CURLOPT_PROTOCOLS_STR (3), .BR CURLOPT_USE_SSL (3)	1.67 KB	2025-07-08 09:41
📄 CURLOPT_FTP_USE_EPRT.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_EPRT.md .TH CURLOPT_FTP_USE_EPRT 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_USE_EPRT \- use EPRT for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_USE_EPRT, long enabled); .fi .SH DESCRIPTION Pass a long. If the value is 1, it tells curl to use the EPRT command when doing active FTP downloads (which is enabled by \fICURLOPT_FTPPORT(3)\fP). Using EPRT means that libcurl first attempts to use EPRT before using PORT, but if you pass zero to this option, it avoids using EPRT, only plain PORT. The EPRT command is a slightly newer addition to the FTP protocol than PORT and is the preferred command to use since it enables IPv6 to be used. Old FTP servers might not support it, which is why libcurl has a fallback mechanism. Sometimes that fallback is not enough and then this option might come handy. If the server is an IPv6 host, this option has no effect as EPRT is necessary then. .SH DEFAULT .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); /* contact us back, aka "active" FTP / curl_easy_setopt(curl, CURLOPT_FTPPORT, "-"); / FTP the way the neanderthals did it */ curl_easy_setopt(curl, CURLOPT_FTP_USE_EPRT, 0L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTPPORT (3), .BR CURLOPT_FTP_USE_EPSV (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_FTP_USE_EPSV.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_EPSV.md .TH CURLOPT_FTP_USE_EPSV 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_USE_EPSV \- use EPSV for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_USE_EPSV, long epsv); .fi .SH DESCRIPTION Pass \fIepsv\fP as a long. If the value is 1, it tells curl to use the EPSV command when doing passive FTP downloads (which it does by default). Using EPSV means that libcurl first attempts to use the EPSV command before using PASV. If you pass zero to this option, it does not use EPSV, only plain PASV. The EPSV command is a slightly newer addition to the FTP protocol than PASV and is the preferred command to use since it enables IPv6 to be used. Old FTP servers might not support it, which is why libcurl has a fallback mechanism. Sometimes that fallback is not enough and then this option might come handy. If the server is an IPv6 host, this option has no effect. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt"); /* let's shut off this modern feature */ curl_easy_setopt(curl, CURLOPT_FTP_USE_EPSV, 0L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTPPORT (3), .BR CURLOPT_FTP_USE_EPRT (3)	1.66 KB	2025-07-08 09:41
📄 CURLOPT_FTP_USE_PRET.3 .\" generated by cd2nroff 0.1 from CURLOPT_FTP_USE_PRET.md .TH CURLOPT_FTP_USE_PRET 3 "2025-06-27" libcurl .SH NAME CURLOPT_FTP_USE_PRET \- use PRET for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_FTP_USE_PRET, long enable); .fi .SH DESCRIPTION Pass a long. If the value is 1, it tells curl to send a PRET command before PASV (and EPSV). Certain FTP servers, mainly drftpd, require this non\-standard command for directory listings as well as up and downloads in PASV mode. Has no effect when using the active FTP transfers mode. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt"); /* a drftpd server, do it */ curl_easy_setopt(curl, CURLOPT_FTP_USE_PRET, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_USE_EPRT (3), .BR CURLOPT_FTP_USE_EPSV (3)	1.28 KB	2025-07-08 09:41
📄 CURLOPT_GSSAPI_DELEGATION.3 .\" generated by cd2nroff 0.1 from CURLOPT_GSSAPI_DELEGATION.md .TH CURLOPT_GSSAPI_DELEGATION 3 "2025-06-27" libcurl .SH NAME CURLOPT_GSSAPI_DELEGATION \- allowed GSS\-API delegation .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_GSSAPI_DELEGATION, long level); .fi .SH DESCRIPTION Set the long parameter \fIlevel\fP to \fBCURLGSSAPI_DELEGATION_FLAG\fP to allow unconditional GSSAPI credential delegation. The delegation is disabled by default since 7.21.7. Set the parameter to \fBCURLGSSAPI_DELEGATION_POLICY_FLAG\fP to delegate only if the OK\-AS\-DELEGATE flag is set in the service ticket in case this feature is supported by the GSS\-API implementation and the definition of \fIGSS_C_DELEG_POLICY_FLAG\fP was available at compile\-time. .SH DEFAULT CURLGSSAPI_DELEGATION_NONE .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* delegate if okayed by policy */ curl_easy_setopt(curl, CURLOPT_GSSAPI_DELEGATION, (long)CURLGSSAPI_DELEGATION_POLICY_FLAG); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.22.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PROXYAUTH (3)	1.5 KB	2025-07-08 09:41
📄 CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.md .TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS \- head start for IPv6 for happy eyeballs .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, long timeout); .fi .SH DESCRIPTION Happy eyeballs is an algorithm that attempts to connect to both IPv4 and IPv6 addresses for dual\-stack hosts, preferring IPv6 first for \fItimeout\fP milliseconds. If the IPv6 address cannot be connected to within that time then a connection attempt is made to the IPv4 address in parallel. The first connection to be established is the one that is used. The range of suggested useful values for \fItimeout\fP is limited. Happy Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced 150\-250 ms apart to balance human factors against network load." libcurl currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms. .SH DEFAULT CURL_HET_DEFAULT (currently defined as 200L) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS, 300L); curl_easy_perform(curl); /* always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.59.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT_MS (3), .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TIMEOUT (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_HAPROXYPROTOCOL.3 .\" generated by cd2nroff 0.1 from CURLOPT_HAPROXYPROTOCOL.md .TH CURLOPT_HAPROXYPROTOCOL 3 "2025-06-27" libcurl .SH NAME CURLOPT_HAPROXYPROTOCOL \- send HAProxy PROXY protocol v1 header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HAPROXYPROTOCOL, long haproxy_protocol); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to send an HAProxy PROXY protocol v1 header at beginning of the connection. The default action is not to send this header. This option is primarily useful when sending test requests to a service that expects this header. Most applications do not need this option. .SH DEFAULT 0, do not send any HAProxy PROXY protocol header .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HAPROXYPROTOCOL, 1L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.60.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3)	1.3 KB	2025-07-08 09:41
📄 CURLOPT_HAPROXY_CLIENT_IP.3 .\" generated by cd2nroff 0.1 from CURLOPT_HAPROXY_CLIENT_IP.md .TH CURLOPT_HAPROXY_CLIENT_IP 3 "2025-06-27" libcurl .SH NAME CURLOPT_HAPROXY_CLIENT_IP \- set HAProxy PROXY protocol client IP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HAPROXY_CLIENT_IP, char client_ip); .fi .SH DESCRIPTION When this parameter is set to a valid IPv4 or IPv6 numerical address, the library sends this address as client address in the HAProxy PROXY protocol v1 header at beginning of the connection. This option is an alternative to \fICURLOPT_HAPROXYPROTOCOL(3)\fP as that one cannot use a specified address. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL, no HAProxy header is sent .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HAPROXY_CLIENT_IP, "1.1.1.1"); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 8.2.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HAPROXYPROTOCOL (3), .BR CURLOPT_PROXY (3)	1.52 KB	2025-07-08 09:41
📄 CURLOPT_HEADER.3 .\" generated by cd2nroff 0.1 from CURLOPT_HEADER.md .TH CURLOPT_HEADER 3 "2025-06-27" libcurl .SH NAME CURLOPT_HEADER \- pass headers to the data stream .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HEADER, long onoff); .fi .SH DESCRIPTION Pass the long value \fIonoff\fP set to 1 to ask libcurl to include the headers in the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP). This option is relevant for protocols that actually have headers or other meta\-data (like HTTP and FTP). When asking to get the headers passed to the same callback as the body, it is not possible to accurately separate them again without detailed knowledge about the protocol in use. Further: the \fICURLOPT_WRITEFUNCTION(3)\fP callback is limited to only ever get a maximum of \fICURL_MAX_WRITE_SIZE\fP bytes passed to it (16KB), while a header can be longer and the \fICURLOPT_HEADERFUNCTION(3)\fP supports getting called with headers up to \fICURL_MAX_HTTP_HEADER\fP bytes big (100KB). It is often better to use \fICURLOPT_HEADERFUNCTION(3)\fP to get the header data separately. While named confusingly similar, \fICURLOPT_HTTPHEADER(3)\fP is used to set custom HTTP headers. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects ftp, http, imap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HEADER, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADERFUNCTION (3), .BR CURLOPT_HTTPHEADER (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_HEADERDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_HEADERDATA.md .TH CURLOPT_HEADERDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_HEADERDATA \- pointer to pass to header callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HEADERDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP to be used to write the header part of the received data to. If \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP is used, \fIpointer\fP is passed in to the respective callback. If neither of those options are set, \fIpointer\fP must be a valid FILE * and it is used by a plain fwrite() to write headers to. If you are using libcurl as a Windows DLL, you \fBMUST\fP use a \fICURLOPT_WRITEFUNCTION(3)\fP or \fICURLOPT_HEADERFUNCTION(3)\fP if you set this option or you might experience crashes. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct my_info { int shoesize; char secret; }; static size_t header_callback(char buffer, size_t size, size_t nitems, void userdata) { struct my_info i = userdata; printf("shoe size: %d\\n", i->shoesize); /* now this callback can access the my_info struct / return nitems size; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct my_info my = { 10, "the cookies are in the cupboard" }; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); / pass in custom data to the callback */ curl_easy_setopt(curl, CURLOPT_HEADERDATA, &my); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADERFUNCTION (3), .BR CURLOPT_WRITEFUNCTION (3), .BR curl_easy_header (3)	1.96 KB	2025-07-08 09:41
📄 CURLOPT_HEADERFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_HEADERFUNCTION.md .TH CURLOPT_HEADERFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_HEADERFUNCTION \- callback that receives header data .SH SYNOPSIS .nf #include <curl/curl.h> size_t header_callback(char buffer, size_t size, size_t nitems, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_HEADERFUNCTION, header_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets invoked by libcurl as soon as it has received header data. The header callback is called once for each header and only complete header lines are passed on to the callback. Parsing headers is easy to do using this callback. \fIbuffer\fP points to the delivered data, and the size of that data is \fInitems\fP; \fIsize\fP is always 1. The provided header line is not null\-terminated. Do not modify the passed in buffer. The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_HEADERDATA(3)\fP option. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to get aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) A complete HTTP header that is passed to this function can be up to \fICURL_MAX_HTTP_HEADER\fP (100K) bytes and includes the final line terminator. If this option is not set, or if it is set to NULL, but \fICURLOPT_HEADERDATA(3)\fP is set to anything but NULL, the function used to accept response data is used instead. That is the function specified with \fICURLOPT_WRITEFUNCTION(3)\fP, or if it is not specified or NULL \- the default, stream\-writing function. It is important to note that the callback is invoked for the headers of all responses received after initiating a request and not just the final response. This includes all responses which occur during authentication negotiation. If you need to operate on only the headers from the final response, you need to collect headers in the callback yourself and use HTTP status lines, for example, to delimit response boundaries. For an HTTP transfer, the status line and the blank line preceding the response body are both included as headers and passed to this function. When a server sends a chunked encoded transfer, it may contain a trailer. That trailer is identical to an HTTP header and if such a trailer is received it is passed to the application using this callback as well. There are several ways to detect it being a trailer and not an ordinary header: 1) it comes after the response\-body. 2) it comes after the final header line (CR LF) 3) a Trailer: header among the regular response\-headers mention what header(s) to expect in the trailer. For non\-HTTP protocols like FTP, POP3, IMAP and SMTP this function gets called with the server responses to the commands that libcurl sends. A more convenient way to get HTTP headers might be to use \fIcurl_easy_header(3)\fP. .SH LIMITATIONS libcurl does not unfold HTTP "folded headers" (deprecated since RFC 7230). A folded header is a header that continues on a subsequent line and starts with a whitespace. Such folds are passed to the header callback as separate ones, although strictly they are just continuations of the previous lines. .SH DEFAULT Nothing. .SH PROTOCOLS This functionality affects ftp, http, imap, pop3 and smtp .SH EXAMPLE .nf static size_t header_callback(char buffer, size_t size, size_t nitems, void userdata) { / received header is nitems * size long in 'buffer' NOT ZERO TERMINATED / / 'userdata' is set with CURLOPT_HEADERDATA / return nitems size; } int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HEADERFUNCTION, header_callback); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.7.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADERDATA (3), .BR CURLOPT_WRITEFUNCTION (3), .BR curl_easy_header (3)	4.42 KB	2025-07-08 09:41
📄 CURLOPT_HEADEROPT.3 .\" generated by cd2nroff 0.1 from CURLOPT_HEADEROPT.md .TH CURLOPT_HEADEROPT 3 "2025-06-27" libcurl .SH NAME CURLOPT_HEADEROPT \- send HTTP headers to both proxy and host or separately .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HEADEROPT, long bitmask); .fi .SH DESCRIPTION Pass a long that is a bitmask of options of how to deal with headers. The two mutually exclusive options are: \fBCURLHEADER_UNIFIED\fP \- the headers specified in \fICURLOPT_HTTPHEADER(3)\fP are used in requests both to servers and proxies. With this option enabled, \fICURLOPT_PROXYHEADER(3)\fP does not have any effect. \fBCURLHEADER_SEPARATE\fP \- makes \fICURLOPT_HTTPHEADER(3)\fP headers only get sent to a server and not to a proxy. Proxy headers must be set with \fICURLOPT_PROXYHEADER(3)\fP to get used. Note that if a non\-CONNECT request is sent to a proxy, libcurl sends both server headers and proxy headers. When doing CONNECT, libcurl sends \fICURLOPT_PROXYHEADER(3)\fP headers only to the proxy and then \fICURLOPT_HTTPHEADER(3)\fP headers only to the server. .SH DEFAULT CURLHEADER_SEPARATE (changed in 7.42.1, used CURLHEADER_UNIFIED before then) .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; struct curl_slist list; list = curl_slist_append(NULL, "Shoesize: 10"); list = curl_slist_append(list, "Accept:"); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); / HTTPS over a proxy makes a separate CONNECT to the proxy, so tell libcurl to not send the custom headers to the proxy. Keep them separate. */ curl_easy_setopt(curl, CURLOPT_HEADEROPT, (long)CURLHEADER_SEPARATE); ret = curl_easy_perform(curl); curl_slist_free_all(list); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.37.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_PROXYHEADER (3)	2.24 KB	2025-07-08 09:41
📄 CURLOPT_HSTS.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTS.md .TH CURLOPT_HSTS 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTS \- HSTS cache filename .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTS, char filename); .fi .SH DESCRIPTION Make the \fIfilename\fP point to a filename to load an existing HSTS cache from, and to store the cache in when the easy handle is closed. Setting a file name with this option also enables HSTS for this handle (the equivalent of setting \fICURLHSTS_ENABLE\fP with \fICURLOPT_HSTS_CTRL(3)\fP). If the given file does not exist or contains no HSTS entries at startup, the HSTS cache simply starts empty. Setting the filename to NULL allows HSTS without reading from or writing to any file. NULL also makes libcurl clear the list of files to read HSTS data from, if any such were previously set. If this option is set multiple times, libcurl loads cache entries from each given file but only stores the last used name for later writing. .SH FILE FORMAT The HSTS cache is saved to and loaded from a text file with one entry per physical line. Each line in the file has the following format: .nf [host] [stamp] .fi [host] is the domain name for the entry and the name is dot\-prefixed if it is an entry valid for all subdomains to the name as well or only for the exact name. [stamp] is the time (in UTC) when the entry expires and it uses the format \&"YYYYMMDD HH:MM:SS". Lines starting with "#" are treated as comments and are ignored. There is currently no length or size limit. .SH DEFAULT NULL, no filename .SH SECURITY CONCERNS libcurl cannot fully protect against attacks where an attacker has write access to the same directory where it is directed to save files. This is particularly sensitive if you save files using elevated privileges. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_HSTS, "/home/user/.hsts-cache"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ALTSVC (3), .BR CURLOPT_HSTS_CTRL (3), .BR CURLOPT_RESOLVE (3)	2.32 KB	2025-07-08 09:41
📄 CURLOPT_HSTSREADDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTSREADDATA.md .TH CURLOPT_HSTSREADDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTSREADDATA \- pointer passed to the HSTS read callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTSREADDATA, void pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the HSTS read function. If you use the \fICURLOPT_HSTSREADFUNCTION(3)\fP option, this is the pointer you get as input in the 3rd argument to the callback. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf struct MyData { void custom; }; int main(void) { CURL curl = curl_easy_init(); struct MyData this; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); /* pass pointer that gets passed in to the CURLOPT_HSTSREADFUNCTION callback */ curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &this); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HSTS (3), .BR CURLOPT_HSTSREADFUNCTION (3), .BR CURLOPT_HSTSWRITEDATA (3), .BR CURLOPT_HSTSWRITEFUNCTION (3)	1.23 KB	2025-07-08 09:41
📄 CURLOPT_HSTSREADFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTSREADFUNCTION.md .TH CURLOPT_HSTSREADFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts .SH SYNOPSIS .nf #include <curl/curl.h> struct curl_hstsentry { char name; size_t namelen; unsigned int includeSubDomains:1; char expire[18]; / YYYYMMDD HH:MM:SS [null-terminated] / }; CURLSTScode hstsread(CURL easy, struct curl_hstsentry sts, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTSREADFUNCTION, hstsread); .fi .SH DESCRIPTION Pass a pointer to your callback function, as the prototype shows above. This callback function gets called by libcurl repeatedly when it populates the in\-memory HSTS cache. Set the \fIclientp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option or it is NULL. When this callback is invoked, the \fIsts\fP pointer points to a populated struct: Copy the hostname to \fIname\fP (no longer than \fInamelen\fP bytes). Make it null\-terminated. Set \fIincludeSubDomains\fP to TRUE or FALSE. Set \fIexpire\fP to a date stamp or a zero length string for \fIforever\fP (wrong date stamp format might cause the name to not get accepted) The callback should return \fICURLSTS_OK\fP if it returns a name and is prepared to be called again (for another host) or \fICURLSTS_DONE\fP if it has no entry to return. It can also return \fICURLSTS_FAIL\fP to signal error. Returning \fICURLSTS_FAIL\fP stops the transfer from being performed and make \fICURLE_ABORTED_BY_CALLBACK\fP get returned. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT NULL \- no callback. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf struct priv { void custom; }; static CURLSTScode hsts_cb(CURL easy, struct curl_hstsentry sts, void clientp) { / populate the struct as documented / return CURLSTS_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct priv my_stuff; CURLcode res; /* set HSTS read callback / curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hsts_cb); / pass in suitable argument to the callback */ curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &my_stuff); res = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HSTS (3), .BR CURLOPT_HSTSREADDATA (3), .BR CURLOPT_HSTSWRITEFUNCTION (3), .BR CURLOPT_HSTS_CTRL (3)	2.45 KB	2025-07-08 09:41
📄 CURLOPT_HSTSWRITEDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTSWRITEDATA.md .TH CURLOPT_HSTSWRITEDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTSWRITEDATA \- pointer passed to the HSTS write callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTSWRITEDATA, void pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the HSTS write function. If you use the \fICURLOPT_HSTSWRITEFUNCTION(3)\fP option, this is the pointer you get as input in the fourth argument to the callback. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf struct MyData { void custom; }; int main(void) { CURL curl = curl_easy_init(); struct MyData this; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); /* pass pointer that gets passed in to the CURLOPT_HSTSWRITEFUNCTION callback */ curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &this); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HSTS (3), .BR CURLOPT_HSTSREADDATA (3), .BR CURLOPT_HSTSREADFUNCTION (3), .BR CURLOPT_HSTSWRITEFUNCTION (3)	1.25 KB	2025-07-08 09:41
📄 CURLOPT_HSTSWRITEFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTSWRITEFUNCTION.md .TH CURLOPT_HSTSWRITEFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts .SH SYNOPSIS .nf #include <curl/curl.h> struct curl_hstsentry { char name; size_t namelen; unsigned int includeSubDomains:1; char expire[18]; / YYYYMMDD HH:MM:SS [null-terminated] / }; struct curl_index { size_t index; / the provided entry's "index" or count / size_t total; / total number of entries to save / }; CURLSTScode hstswrite(CURL easy, struct curl_hstsentry sts, struct curl_index count, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTSWRITEFUNCTION, hstswrite); .fi .SH DESCRIPTION Pass a pointer to your callback function, as the prototype shows above. This callback function gets called by libcurl repeatedly to allow the application to store the in\-memory HSTS cache when libcurl is about to discard it. Set the \fIclientp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option or it is NULL. When the callback is invoked, the \fIsts\fP pointer points to a populated struct: Read the hostname to \(aqname\(aq (it is \fInamelen\fP bytes long and null terminated. The \fIincludeSubDomains\fP field is non\-zero if the entry matches subdomains. The \fIexpire\fP string is a date stamp null\-terminated string using the syntax YYYYMMDD HH:MM:SS. The callback should return \fICURLSTS_OK\fP if it succeeded and is prepared to be called again (for another host) or \fICURLSTS_DONE\fP if there is nothing more to do. It can also return \fICURLSTS_FAIL\fP to signal error. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT NULL \- no callback. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf struct priv { void custom; }; static CURLSTScode hswr_cb(CURL easy, struct curl_hstsentry sts, struct curl_index count, void clientp) { / save the passed in HSTS data somewhere / return CURLSTS_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct priv my_stuff; CURLcode res; /* set HSTS read callback / curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hswr_cb); / pass in suitable argument to the callback */ curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &my_stuff); res = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HSTS (3), .BR CURLOPT_HSTSWRITEDATA (3), .BR CURLOPT_HSTSWRITEFUNCTION (3), .BR CURLOPT_HSTS_CTRL (3)	2.58 KB	2025-07-08 09:41
📄 CURLOPT_HSTS_CTRL.3 .\" generated by cd2nroff 0.1 from CURLOPT_HSTS_CTRL.md .TH CURLOPT_HSTS_CTRL 3 "2025-06-27" libcurl .SH NAME CURLOPT_HSTS_CTRL \- control HSTS behavior .SH SYNOPSIS .nf #include <curl/curl.h> #define CURLHSTS_ENABLE (1<<0) #define CURLHSTS_READONLYFILE (1<<1) CURLcode curl_easy_setopt(CURL handle, CURLOPT_HSTS_CTRL, long bitmask); .fi .SH DESCRIPTION HSTS (HTTP Strict Transport Security) means that an HTTPS server can instruct the client to not contact it again over clear\-text HTTP for a certain period into the future. libcurl then automatically redirects HTTP attempts to such hosts to instead use HTTPS. This is done by libcurl retaining this knowledge in an in\-memory cache. Populate the long \fIbitmask\fP with the correct set of features to instruct libcurl how to handle HSTS for the transfers using this handle. .SH BITS .IP CURLHSTS_ENABLE Enable the in\-memory HSTS cache for this handle. .IP CURLHSTS_READONLYFILE Make the HSTS file (if specified) read\-only \- makes libcurl not save the cache to the file when closing the handle. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, (long)CURLHSTS_ENABLE); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.74.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ALTSVC (3), .BR CURLOPT_CONNECT_TO (3), .BR CURLOPT_HSTS (3), .BR CURLOPT_RESOLVE (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_HTTP09_ALLOWED.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTP09_ALLOWED.md .TH CURLOPT_HTTP09_ALLOWED 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTP09_ALLOWED \- allow HTTP/0.9 response .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTP09_ALLOWED, long allowed); .fi .SH DESCRIPTION Pass the long argument \fIallowed\fP set to 1L to allow HTTP/0.9 responses. An HTTP/0.9 response is a server response entirely without headers and only a body. You can connect to lots of random TCP services and still get a response that curl might consider to be HTTP/0.9. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HTTP09_ALLOWED, 1L); ret = curl_easy_perform(curl); } } .fi .SH HISTORY curl allowed HTTP/0.9 responses by default before 7.66.0 Since 7.66.0, libcurl requires this option set to 1L to allow HTTP/0.9 responses. .SH AVAILABILITY Added in curl 7.64.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_SSLVERSION (3)	1.33 KB	2025-07-08 09:41
📄 CURLOPT_HTTP200ALIASES.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTP200ALIASES.md .TH CURLOPT_HTTP200ALIASES 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTP200ALIASES \- alternative matches for HTTP 200 OK .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTP200ALIASES, struct curl_slist aliases); .fi .SH DESCRIPTION Pass a pointer to a linked list of \fIaliases\fP to be treated as valid HTTP 200 responses. Some servers respond with a custom header response line. For example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast 1.3.x servers respond like that for certain user agent headers or in absence of such. By including this string in your list of aliases, the response gets treated as a valid HTTP header line such as "HTTP/1.0 200 OK". The linked list should be a fully valid list of struct curl_slist structs, and be properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. The alias itself is not parsed for any version strings. The protocol is assumed to match HTTP 1.0 when an alias match. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { struct curl_slist list; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); list = curl_slist_append(NULL, "ICY 200 OK"); list = curl_slist_append(list, "WEIRDO 99 FINE"); curl_easy_setopt(curl, CURLOPT_HTTP200ALIASES, list); curl_easy_perform(curl); curl_slist_free_all(list); /* free the list again */ } } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP09_ALLOWED (3), .BR CURLOPT_HTTP_VERSION (3)	2.13 KB	2025-07-08 09:41
📄 CURLOPT_HTTPAUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTPAUTH.md .TH CURLOPT_HTTPAUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTPAUTH \- HTTP server authentication methods to try .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTPAUTH, long bitmask); .fi .SH DESCRIPTION Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) you want it to use speaking to the remote server. The available bits are listed below. If more than one bit is set, libcurl first queries the host to see which authentication methods it supports and then picks the best one you allow it to use. For some methods, this induces an extra network round\-trip. Set the actual name and password with the \fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the \fICURLOPT_PASSWORD(3)\fP options. For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP. .IP CURLAUTH_BASIC HTTP Basic authentication. This is the default choice, and the only method that is in wide\-spread use and supported virtually everywhere. This sends the username and password over the network in plain text, easily captured by others. .IP CURLAUTH_DIGEST HTTP Digest authentication. Digest authentication is defined in RFC 2617 and is a more secure way to do authentication over public networks than the regular old\-fashioned Basic method. .IP CURLAUTH_DIGEST_IE HTTP Digest authentication with an IE flavor. Digest authentication is defined in RFC 2617 and is a more secure way to do authentication over public networks than the regular old\-fashioned Basic method. The IE flavor is simply that libcurl uses a special "quirk" that IE is known to have used before version 7 and that some servers require the client to use. .IP CURLAUTH_BEARER HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol. You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP. .IP CURLAUTH_NEGOTIATE HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined in RFC 4559 and is the most secure way to perform authentication over HTTP. You need to build libcurl with a suitable GSS\-API library or SSPI on Windows for this to work. .IP CURLAUTH_NTLM HTTP NTLM authentication. A proprietary protocol invented and used by Microsoft. It uses a challenge\-response and hash concept similar to Digest, to prevent the password from being eavesdropped. NTLM uses weak cryptographic algorithms and is not considered secure. .IP CURLAUTH_NTLM_WB Support for this is removed since libcurl 8.8.0. NTLM delegating to winbind helper. Authentication is performed by a separate binary application that is executed when needed. The name of the application is specified at compile time but is typically \fB/usr/bin/ntlm_auth\fP. Note that libcurl forks when necessary to run the winbind application and kill it when complete, calling \fBwaitpid()\fP to await its exit when done. On POSIX operating systems, killing the process causes a SIGCHLD signal to be raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be handled intelligently by the application. In particular, the application must not unconditionally call wait() in its SIGCHLD signal handler to avoid being subject to a race condition. This behavior is subject to change in future versions of libcurl. .IP CURLAUTH_ANY This is a convenience macro that sets all bits and thus makes libcurl pick any it finds suitable. libcurl automatically selects the one it finds most secure. .IP CURLAUTH_ANYSAFE This is a convenience macro that sets all bits except Basic and thus makes libcurl pick any it finds suitable. libcurl automatically selects the one it finds most secure. .IP CURLAUTH_ONLY This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for unrestricted auth and if not, only that single auth algorithm is acceptable. .IP CURLAUTH_AWS_SIGV4 provides AWS V4 signature authentication on HTTPS header see \fICURLOPT_AWS_SIGV4(3)\fP. .SH DEFAULT CURLAUTH_BASIC .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* allow whatever auth the server speaks */ curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_ANY); curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond"); ret = curl_easy_perform(curl); } } .fi .SH HISTORY CURLAUTH_DIGEST_IE was added in 7.19.3 CURLAUTH_ONLY was added in 7.21.3 CURLAUTH_NTLM_WB was added in 7.22.0 CURLAUTH_BEARER was added in 7.61.0 CURLAUTH_AWS_SIGV4 was added in 7.74.0 .SH AVAILABILITY Added in curl 7.10.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PASSWORD (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_USERNAME (3)	4.9 KB	2025-07-08 09:41
📄 CURLOPT_HTTPGET.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTPGET.md .TH CURLOPT_HTTPGET 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTPGET \- ask for an HTTP GET request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTPGET, long useget); .fi .SH DESCRIPTION Pass a long. If \fIuseget\fP is 1, this forces the HTTP request to get back to using GET. Usable if a POST, HEAD, PUT, etc has been used previously using the same curl \fIhandle\fP. When setting \fICURLOPT_HTTPGET(3)\fP to 1, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP to 0 and \fICURLOPT_UPLOAD(3)\fP to 0. Setting this option to zero has no effect. Applications need to explicitly select which HTTP request method to use, they cannot deselect a method. To reset a handle to default method, consider \fIcurl_easy_reset(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* use a GET to fetch this / curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.8.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NOBODY (3), .BR CURLOPT_POST (3), .BR CURLOPT_UPLOAD (3), .BR curl_easy_reset (3)	1.49 KB	2025-07-08 09:41
📄 CURLOPT_HTTPHEADER.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTPHEADER.md .TH CURLOPT_HTTPHEADER 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTPHEADER \- set of HTTP headers .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTPHEADER, struct curl_slist headers); .fi .SH DESCRIPTION Pass a pointer to a linked list of HTTP headers to pass to the server and/or proxy in your HTTP request. The same list can be used for both host and proxy requests. When used within an IMAP or SMTP request to upload a MIME mail, the given header list establishes the document\-level MIME headers to prepend to the uploaded document described by \fICURLOPT_MIMEPOST(3)\fP. This does not affect raw mail uploads. When used with HTTP, this option can add new headers, replace internal headers and remove internal headers. The linked list should be a valid list of \fBstruct curl_slist\fP entries properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to free it again after use. If you provide a header that is otherwise generated and used by libcurl internally, your header alternative is used instead. If you provide a header without content (no data on the right side of the colon) as in \fIAccept:\fP, the internally used header is removed. To forcibly add a header without content (nothing after the colon), use the form \fIname;\fP (using a trailing semicolon). The headers included in the linked list \fBmust not\fP be CRLF\-terminated, since libcurl adds CRLF after each header item itself. Failure to comply with this might result in strange behavior. libcurl passes on the verbatim strings you give it, without any filter or other safe guards. That includes white space and control characters. The first line in an HTTP request (containing the method, usually a GET or POST) is not a header and cannot be replaced using this option. Only the lines following the request\-line are headers. Adding this method line in this list of headers only causes your request to send an invalid header. Use \fICURLOPT_CUSTOMREQUEST(3)\fP to change the method. When this option is passed to \fIcurl_easy_setopt(3)\fP, libcurl does not copy the entire list so you \fBmust\fP keep it around until you no longer use this \fIhandle\fP for a transfer before you call \fIcurl_slist_free_all(3)\fP on the list. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. The most commonly replaced HTTP headers have "shortcuts" in the options \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP and \fICURLOPT_REFERER(3)\fP. We recommend using those. There is an alternative option that sets or replaces headers only for requests that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER(3)\fP. Use \fICURLOPT_HEADEROPT(3)\fP to control the behavior. .SH SPECIFIC HTTP HEADERS Setting some specific headers causes libcurl to act differently. .IP Host: The specified hostname is used for cookie matching if the cookie engine is also enabled for this transfer. If the request is done over HTTP/2 or HTTP/3, the custom hostname is instead used in the ":authority" header field and Host: is not sent at all over the wire. .IP "Transfer-Encoding: chunked" Tells libcurl the upload is to be done using this chunked encoding instead of providing the Content\-Length: field in the request. .SH SPECIFIC MIME HEADERS When used to build a MIME email for IMAP or SMTP, the following document\-level headers can be set to override libcurl\-generated values: .IP Mime-Version: Tells the parser at the receiving site how to interpret the MIME framing. It defaults to "1.0" and should normally not be altered. .IP Content-Type: Indicates the document\(aqs global structure type. By default, libcurl sets it to "multipart/mixed", describing a document made of independent parts. When a MIME mail is only composed of alternative representations of the same data (i.e.: HTML and plain text), this header must be set to "multipart/alternative". In all cases the value must be of the form "multipart/" to respect the document structure and may not include the "boundary=" parameter. .PP Other specific headers that do not have a libcurl default value but are strongly desired by mail delivery and user agents should also be included. These are \fIFrom:\fP, \fITo:\fP, \fIDate:\fP and \fISubject:\fP among others and their presence and value is generally checked by anti\-spam utilities. .SH SECURITY CONCERNS By default, this option makes libcurl send the given headers in all HTTP requests done by this handle. You should therefore use this option with caution if you for example connect to the remote site using a proxy and a CONNECT request, you should to consider if that proxy is supposed to also get the headers. They may be private or otherwise sensitive to leak. Use \fICURLOPT_HEADEROPT(3)\fP to make the headers only get sent to where you intend them to get sent. Custom headers are sent in all requests done by the easy handle, which implies that if you tell libcurl to follow redirects (\fICURLOPT_FOLLOWLOCATION(3)\fP), the same set of custom headers is sent in the subsequent request. Redirects can of course go to other hosts and thus those servers get all the contents of your custom headers too. Starting in 7.58.0, libcurl specifically prevents "Authorization:" headers from being sent to other hosts than the first used one, unless specifically permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. Starting in 7.64.0, libcurl specifically prevents "Cookie:" headers from being sent to other hosts than the first used one, unless specifically permitted with the \fICURLOPT_UNRESTRICTED_AUTH(3)\fP option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); struct curl_slist list = NULL; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / add this header / list = curl_slist_append(list, "Shoesize: 10"); / remove this header / list = curl_slist_append(list, "Accept:"); / change this header / list = curl_slist_append(list, "Host: example.net"); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); curl_easy_perform(curl); curl_slist_free_all(list); / free the list */ } } .fi .SH HISTORY Use for MIME mail added in 7.56.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_HEADER (3), .BR CURLOPT_HEADEROPT (3), .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_PROXYHEADER (3), .BR curl_mime_init (3)	6.7 KB	2025-07-08 09:41
📄 CURLOPT_HTTPPOST.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTPPOST.md .TH CURLOPT_HTTPPOST 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTPPOST \- multipart formpost content .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTPPOST, struct curl_httppost formpost); .fi .SH DESCRIPTION \fBThis option is deprecated.\fP Use \fICURLOPT_MIMEPOST(3)\fP instead. Tells libcurl you want a \fBmultipart/formdata\fP HTTP POST to be made and you instruct what data to pass on to the server in the \fIformpost\fP argument. Pass a pointer to a linked list of \fIcurl_httppost\fP structs as parameter. The easiest way to create such a list, is to use \fIcurl_formadd(3)\fP as documented. The data in this list must remain intact as long as the curl transfer is alive and is using it. Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP. When setting \fICURLOPT_HTTPPOST(3)\fP, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP to 0. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { struct curl_httppost formpost; struct curl_httppost lastptr; /* Fill in the file upload field. This makes libcurl load data from the given file name when curl_easy_perform() is called. / curl_formadd(&formpost, &lastptr, CURLFORM_COPYNAME, "sendfile", CURLFORM_FILE, "postit2.c", CURLFORM_END); / Fill in the filename field / curl_formadd(&formpost, &lastptr, CURLFORM_COPYNAME, "filename", CURLFORM_COPYCONTENTS, "postit2.c", CURLFORM_END); / Fill in the submit field too, even if this is rarely needed / curl_formadd(&formpost, &lastptr, CURLFORM_COPYNAME, "submit", CURLFORM_COPYCONTENTS, "send", CURLFORM_END); CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); curl_easy_perform(curl); curl_easy_cleanup(curl); } curl_formfree(formpost); } .fi .SH DEPRECATED Deprecated in 7.56.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_POST (3), .BR CURLOPT_POSTFIELDS (3), .BR curl_formadd (3), .BR curl_formfree (3), .BR curl_mime_init (3)	2.55 KB	2025-07-08 09:41
📄 CURLOPT_HTTPPROXYTUNNEL.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTPPROXYTUNNEL.md .TH CURLOPT_HTTPPROXYTUNNEL 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTPPROXYTUNNEL \- tunnel through HTTP proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTPPROXYTUNNEL, long tunnel); .fi .SH DESCRIPTION Set the \fBtunnel\fP parameter to 1L to make libcurl tunnel all operations through the HTTP proxy (set with \fICURLOPT_PROXY(3)\fP). There is a big difference between using a proxy and to tunnel through it. Tunneling means that an HTTP CONNECT request is sent to the proxy, asking it to connect to a remote host on a specific port number and then the traffic is just passed through the proxy. Proxies tend to white\-list specific port numbers it allows CONNECT requests to and often only port 80 and 443 are allowed. To suppress proxy CONNECT response headers from user callbacks use \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. HTTP proxies can generally only speak HTTP (for obvious reasons), which makes libcurl convert non\-HTTP requests to HTTP when using an HTTP proxy without this tunnel option set. For example, asking for an FTP URL and specifying an HTTP proxy makes libcurl send an FTP URL in an HTTP GET request to the proxy. By instead tunneling through the proxy, you avoid that conversion (that rarely works through the proxy anyway). .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80"); curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYPORT (3), .BR CURLOPT_PROXYTYPE (3)	2.03 KB	2025-07-08 09:41
📄 CURLOPT_HTTP_CONTENT_DECODING.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTP_CONTENT_DECODING.md .TH CURLOPT_HTTP_CONTENT_DECODING 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTP_CONTENT_DECODING \- HTTP content decoding control .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTP_CONTENT_DECODING, long enabled); .fi .SH DESCRIPTION Pass a long to tell libcurl how to act on content decoding. If set to zero, content decoding is disabled. If set to 1 it is enabled. libcurl has no default content decoding but requires you to use \fICURLOPT_ACCEPT_ENCODING(3)\fP for that. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HTTP_CONTENT_DECODING, 0L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ACCEPT_ENCODING (3), .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3)	1.25 KB	2025-07-08 09:41
📄 CURLOPT_HTTP_TRANSFER_DECODING.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTP_TRANSFER_DECODING.md .TH CURLOPT_HTTP_TRANSFER_DECODING 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTP_TRANSFER_DECODING \- HTTP transfer decoding control .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTP_TRANSFER_DECODING, long enabled); .fi .SH DESCRIPTION Pass a long to tell libcurl how to act on transfer decoding. If set to zero, transfer decoding is disabled, if set to 1 it is enabled (default). libcurl does chunked transfer decoding by default unless this option is set to zero. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HTTP_TRANSFER_DECODING, 0L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ACCEPT_ENCODING (3), .BR CURLOPT_HTTP_CONTENT_DECODING (3)	1.23 KB	2025-07-08 09:41
📄 CURLOPT_HTTP_VERSION.3 .\" generated by cd2nroff 0.1 from CURLOPT_HTTP_VERSION.md .TH CURLOPT_HTTP_VERSION 3 "2025-06-27" libcurl .SH NAME CURLOPT_HTTP_VERSION \- HTTP protocol version to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_HTTP_VERSION, long version); .fi .SH DESCRIPTION Pass \fIversion\fP a long, set to one of the values described below. They ask libcurl to use the specific HTTP versions. Note that the HTTP version is just a request. libcurl still prioritizes to reuse existing connections so it might then reuse a connection using an HTTP version you have not asked for. .IP CURL_HTTP_VERSION_NONE We do not care about what version the library uses. libcurl uses whatever it thinks fit. .IP CURL_HTTP_VERSION_1_0 Enforce HTTP 1.0 requests. .IP CURL_HTTP_VERSION_1_1 Enforce HTTP 1.1 requests. .IP CURL_HTTP_VERSION_2_0 Attempt HTTP 2 requests. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be negotiated with the server. (Added in 7.33.0) When libcurl uses HTTP/2 over HTTPS, it does not itself insist on TLS 1.2 or higher even though that is required by the specification. A user can add this version requirement with \fICURLOPT_SSLVERSION(3)\fP. The alias \fICURL_HTTP_VERSION_2\fP was added in 7.43.0 to better reflect the actual protocol name. .IP CURL_HTTP_VERSION_2TLS Attempt HTTP 2 over TLS (HTTPS) only. libcurl falls back to HTTP 1.1 if HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers, libcurl uses 1.1. (Added in 7.47.0) .IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE Issue non\-TLS HTTP requests using HTTP/2 without HTTP/1.1 Upgrade. It requires prior knowledge that the server supports HTTP/2 straight away. HTTPS requests still do HTTP/2 the standard way with negotiated protocol version in the TLS handshake. (Added in 7.49.0) Since 8.10.0 if this option is set for an HTTPS request then the application layer protocol version (ALPN) offered to the server is only HTTP/2. Prior to that both HTTP/1.1 and HTTP/2 were offered. .IP CURL_HTTP_VERSION_3 (Added in 7.66.0) This option makes libcurl attempt to use HTTP/3 to the host given in the URL, with fallback to earlier HTTP versions if needed. .IP CURL_HTTP_VERSION_3ONLY (Added in 7.88.0) Setting this makes libcurl attempt to use HTTP/3 directly to server given in the URL and does not downgrade to earlier HTTP version if the server does not support HTTP/3. .SH DEFAULT Since curl 7.62.0: CURL_HTTP_VERSION_2TLS Before that: CURL_HTTP_VERSION_1_1 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_HTTP_VERSION, (long)CURL_HTTP_VERSION_2TLS); ret = curl_easy_perform(curl); if(ret == CURLE_HTTP_RETURNED_ERROR) { /* an HTTP response error problem */ } } } .fi .SH AVAILABILITY Added in curl 7.9.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ALTSVC (3), .BR CURLOPT_HTTP09_ALLOWED (3), .BR CURLOPT_HTTP200ALIASES (3), .BR CURLOPT_SSLVERSION (3)	3.22 KB	2025-07-08 09:41
📄 CURLOPT_IGNORE_CONTENT_LENGTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_IGNORE_CONTENT_LENGTH.md .TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_IGNORE_CONTENT_LENGTH \- ignore content length .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_IGNORE_CONTENT_LENGTH, long ignore); .fi .SH DESCRIPTION If \fIignore\fP is set to 1L, ignore the Content\-Length header in the HTTP response and ignore asking for or relying on it for FTP transfers. This is useful for doing HTTP transfers with ancient web servers which report incorrect content length for files over 2 gigabytes. If this option is used, curl cannot accurately report progress, and it instead stops the download when the server ends the connection. It is also useful with FTP when for example the file is growing while the transfer is in progress which otherwise unconditionally causes libcurl to report error. Only use this option if strictly necessary. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects ftp and http .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* we know the server is silly, ignore content-length */ curl_easy_setopt(curl, CURLOPT_IGNORE_CONTENT_LENGTH, 1L); curl_easy_perform(curl); } } .fi .SH HISTORY Support for FTP added in 7.46.0. .SH AVAILABILITY Added in curl 7.14.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_MAXFILESIZE_LARGE (3)	1.67 KB	2025-07-08 09:41
📄 CURLOPT_INFILESIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_INFILESIZE.md .TH CURLOPT_INFILESIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_INFILESIZE \- size of the input file to send off .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_INFILESIZE, long filesize); .fi .SH DESCRIPTION When uploading a file to a remote site, \fIfilesize\fP should be used to tell libcurl what the expected size of the input file is. This value must be passed as a long. See also \fICURLOPT_INFILESIZE_LARGE(3)\fP for sending files larger than 2GB. For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE(3)\fP is mandatory. To unset this value again, set it to \-1. Using \fICURLOPT_UPLOAD(3)\fP to an HTTP/1.1 server and this value set to \-1, makes libcurl do a chunked transfer\-encoded upload. When sending emails using SMTP, this command can be used to specify the optional SIZE parameter for the MAIL FROM command. This option does not limit how much data libcurl actually sends, as that is controlled entirely by what the read callback returns, but telling one value and sending a different amount may lead to errors. .SH DEFAULT Unset .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #define FILE_SIZE 12345L int main(void) { CURL curl = curl_easy_init(); if(curl) { long uploadsize = FILE_SIZE; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz"); curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); curl_easy_setopt(curl, CURLOPT_INFILESIZE, uploadsize); curl_easy_perform(curl); } } .fi .SH HISTORY SMTP support added in 7.23.0 .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), .BR CURLOPT_INFILESIZE_LARGE (3), .BR CURLOPT_UPLOAD (3)	1.96 KB	2025-07-08 09:41
📄 CURLOPT_INFILESIZE_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_INFILESIZE_LARGE.md .TH CURLOPT_INFILESIZE_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_INFILESIZE_LARGE \- size of the input file to send off .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_INFILESIZE_LARGE, curl_off_t filesize); .fi .SH DESCRIPTION When uploading a file to a remote site, \fIfilesize\fP should be used to tell libcurl what the expected size of the input file is. This value must be passed as a \fBcurl_off_t\fP. For uploading using SCP, this option or \fICURLOPT_INFILESIZE(3)\fP is mandatory. To unset this value again, set it to \-1. When sending emails using SMTP, this command can be used to specify the optional SIZE parameter for the MAIL FROM command. This option does not limit how much data libcurl actually sends, as that is controlled entirely by what the read callback returns, but telling one value and sending a different amount may lead to errors. .SH DEFAULT Unset .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #define FILE_SIZE 123456 int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_off_t uploadsize = FILE_SIZE; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/destination.tar.gz"); curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, uploadsize); curl_easy_perform(curl); } } .fi .SH HISTORY SMTP support added in 7.23.0 .SH AVAILABILITY Added in curl 7.11.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_LENGTH_UPLOAD_T (3), .BR CURLOPT_INFILESIZE (3), .BR CURLOPT_UPLOAD (3)	1.82 KB	2025-07-08 09:41
📄 CURLOPT_INTERFACE.3 .\" generated by cd2nroff 0.1 from CURLOPT_INTERFACE.md .TH CURLOPT_INTERFACE 3 "2025-06-27" libcurl .SH NAME CURLOPT_INTERFACE \- source interface for outgoing traffic .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_INTERFACE, char interface); .fi .SH DESCRIPTION Pass a char pointer as parameter. This sets the \fIinterface\fP name to use as outgoing network interface. The name can be an interface name, an IP address, or a hostname. If you prefer one of these, you can use the following special prefixes: * \fIif!<name>\fP \- Interface name * \fIhost!<name>\fP \- IP address or hostname * \fIifhost!<interface>!<host>\fP \- Interface name and IP address or hostname If \fIif!\fP or \fIifhost!\fP is specified but the parameter does not match an existing interface, \fICURLE_INTERFACE_FAILED\fP is returned from the libcurl function used to perform the transfer. libcurl does not support using network interface names for this option on Windows. We strongly advise against specifying the interface with a hostname, as it causes libcurl to do a blocking name resolve call to retrieve the IP address. That name resolve operation does \fBnot\fP use DNS\-over\-HTTPS even if \fICURLOPT_DOH_URL(3)\fP is set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL, use whatever the TCP stack finds suitable .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_INTERFACE, "eth0"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY The \fIif!\fP and \fIhost!\fP syntax was added in 7.24.0. The \fIifhost!\fP syntax was added in 8.9.0. .SH AVAILABILITY Added in curl 7.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOCALPORT (3), .BR CURLOPT_SOCKOPTFUNCTION (3), .BR CURLOPT_TCP_NODELAY (3)	2.28 KB	2025-07-08 09:41
📄 CURLOPT_INTERLEAVEDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_INTERLEAVEDATA.md .TH CURLOPT_INTERLEAVEDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_INTERLEAVEDATA \- pointer passed to RTSP interleave callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_INTERLEAVEDATA, void pointer); .fi .SH DESCRIPTION This is the userdata \fIpointer\fP that is passed to \fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If the interleave function callback is not set, this pointer is not used anywhere. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf struct local { void custom; }; static size_t rtp_write(void ptr, size_t size, size_t nmemb, void userp) { struct local l = userp; printf("my pointer: %p\\n", l->custom); /* take care of the packet in 'ptr', then return... / return size nmemb; } int main(void) { struct local rtp_data; CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INTERLEAVEFUNCTION (3), .BR CURLOPT_RTSP_REQUEST (3)	1.42 KB	2025-07-08 09:41
📄 CURLOPT_INTERLEAVEFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_INTERLEAVEFUNCTION.md .TH CURLOPT_INTERLEAVEFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_INTERLEAVEFUNCTION \- callback for RTSP interleaved data .SH SYNOPSIS .nf #include <curl/curl.h> size_t interleave_callback(void ptr, size_t size, size_t nmemb, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_INTERLEAVEFUNCTION, interleave_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl as soon as it has received interleaved RTP data. This function gets called for each $ block and therefore contains exactly one upper\-layer protocol unit (e.g. one RTP packet). curl writes the interleaved header as well as the included data for each call. The first byte is always an ASCII dollar sign. The dollar sign is followed by a one byte channel identifier and then a 2 byte integer length in network byte order. See RFC 2326 Section 10.12 for more information on how RTP interleaving behaves. If unset or set to NULL, curl uses the default write function. Interleaved RTP poses some challenges for the client application. Since the stream data is sharing the RTSP control connection, it is critical to service the RTP in a timely fashion. If the RTP data is not handled quickly, subsequent response processing may become unreasonably delayed and the connection may close. The application may use \fICURL_RTSPREQ_RECEIVE\fP to service RTP data when no requests are desired. If the application makes a request, (e.g. \fICURL_RTSPREQ_PAUSE\fP) then the response handler processes any pending RTP data before marking the request as finished. The \fICURLOPT_INTERLEAVEDATA(3)\fP is passed in the \fIuserdata\fP argument in the callback. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to abort and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR. (7.87.0) .SH DEFAULT NULL, the interleave data is then passed to the regular write function: \fICURLOPT_WRITEFUNCTION(3)\fP. .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf struct local { void custom; }; static size_t rtp_write(void ptr, size_t size, size_t nmemb, void userp) { struct local l = userp; printf("our ptr: %p\\n", l->custom); / take care of the packet in 'ptr', then return... / return size nmemb; } int main(void) { struct local rtp_data; CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_INTERLEAVEFUNCTION, rtp_write); curl_easy_setopt(curl, CURLOPT_INTERLEAVEDATA, &rtp_data); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INTERLEAVEDATA (3), .BR CURLOPT_RTSP_REQUEST (3)	3.13 KB	2025-07-08 09:41
📄 CURLOPT_IOCTLDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_IOCTLDATA.md .TH CURLOPT_IOCTLDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_IOCTLDATA \- pointer passed to I/O callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_IOCTLDATA, void pointer); .fi .SH DESCRIPTION Pass the \fIpointer\fP that is untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <unistd.h> /* for lseek / struct data { int fd; / our file descriptor / }; static curlioerr ioctl_callback(CURL handle, int cmd, void clientp) { struct data io = (struct data )clientp; if(cmd == CURLIOCMD_RESTARTREAD) { lseek(io->fd, 0, SEEK_SET); return CURLIOE_OK; } return CURLIOE_UNKNOWNCMD; } int main(void) { struct data ioctl_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); } } .fi .SH DEPRECATED Deprecated since 7.18.0. .SH AVAILABILITY Added in curl 7.12.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_IOCTLFUNCTION (3), .BR CURLOPT_SEEKFUNCTION (3)	1.41 KB	2025-07-08 09:41
📄 CURLOPT_IOCTLFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_IOCTLFUNCTION.md .TH CURLOPT_IOCTLFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_IOCTLFUNCTION \- callback for I/O operations .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLIOE_OK, /* I/O operation successful / CURLIOE_UNKNOWNCMD, / command was unknown to callback / CURLIOE_FAILRESTART, / failed to restart the read / CURLIOE_LAST / never use / } curlioerr; typedef enum { CURLIOCMD_NOP, / no operation / CURLIOCMD_RESTARTREAD, / restart the read stream from start / CURLIOCMD_LAST / never use / } curliocmd; curlioerr ioctl_callback(CURL handle, int cmd, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_IOCTLFUNCTION, ioctl_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl when something special I/O\-related needs to be done that the library cannot do by itself. For now, rewinding the read data stream is the only action it can request. The rewinding of the read data stream may be necessary when doing an HTTP PUT or POST with a multi\-pass authentication method. The callback MUST return \fICURLIOE_UNKNOWNCMD\fP if the input \fIcmd\fP is not \fICURLIOCMD_RESTARTREAD\fP. The \fIclientp\fP argument to the callback is set with the \fICURLOPT_IOCTLDATA(3)\fP option. \fBThis option is deprecated\fP. Do not use it. Use \fICURLOPT_SEEKFUNCTION(3)\fP instead to provide seeking. If \fICURLOPT_SEEKFUNCTION(3)\fP is set, this parameter is ignored when seeking. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <unistd.h> /* for lseek / struct data { int fd; / our file descriptor / }; static curlioerr ioctl_callback(CURL handle, int cmd, void clientp) { struct data io = (struct data )clientp; if(cmd == CURLIOCMD_RESTARTREAD) { lseek(io->fd, 0, SEEK_SET); return CURLIOE_OK; } return CURLIOE_UNKNOWNCMD; } int main(void) { struct data ioctl_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_IOCTLFUNCTION, ioctl_callback); curl_easy_setopt(curl, CURLOPT_IOCTLDATA, &ioctl_data); } } .fi .SH DEPRECATED Deprecated since 7.18.0. .SH AVAILABILITY Added in curl 7.12.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_IOCTLDATA (3), .BR CURLOPT_SEEKFUNCTION (3)	2.57 KB	2025-07-08 09:41
📄 CURLOPT_IPRESOLVE.3 .\" generated by cd2nroff 0.1 from CURLOPT_IPRESOLVE.md .TH CURLOPT_IPRESOLVE 3 "2025-06-27" libcurl .SH NAME CURLOPT_IPRESOLVE \- IP protocol version to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_IPRESOLVE, long resolve); .fi .SH DESCRIPTION Allows an application to select what kind of IP addresses to use when establishing a connection or choosing one from the connection pool. This is interesting when using hostnames that resolve to more than one IP family. If the URL provided for a transfer contains a numerical IP version as a host name, this option does not override or prohibit libcurl from using that IP version. Available values for this option are: .IP CURL_IPRESOLVE_WHATEVER Default, can use addresses of all IP versions that your system allows. .IP CURL_IPRESOLVE_V4 Uses only IPv4 addresses. .IP CURL_IPRESOLVE_V6 Uses only IPv6 addresses. .SH DEFAULT CURL_IPRESOLVE_WHATEVER .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); /* of all addresses example.com resolves to, only IPv6 ones are used */ curl_easy_setopt(curl, CURLOPT_IPRESOLVE, (long)CURL_IPRESOLVE_V6); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.8 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_RESOLVE (3), .BR CURLOPT_SSLVERSION (3)	1.69 KB	2025-07-08 09:41
📄 CURLOPT_ISSUERCERT.3 .\" generated by cd2nroff 0.1 from CURLOPT_ISSUERCERT.md .TH CURLOPT_ISSUERCERT 3 "2025-06-27" libcurl .SH NAME CURLOPT_ISSUERCERT \- issuer SSL certificate filename .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ISSUERCERT, char file); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a \fIfile\fP holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check is useful in multi\-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option makes sense only when used in combination with the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP has to be set too for the check to fail). (Added in 7.19.0) Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_ISSUERCERT, "/etc/certs/cacert.pem"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CRLFILE (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.19 KB	2025-07-08 09:41
📄 CURLOPT_ISSUERCERT_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_ISSUERCERT_BLOB.md .TH CURLOPT_ISSUERCERT_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_ISSUERCERT_BLOB \- issuer SSL certificate from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_ISSUERCERT_BLOB, struct curl_blob stblob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure, which contains information (pointer and size) about a memory block with binary data of a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer is indeed the one associated with the certificate provided by the option. This additional check is useful in multi\-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option should be used in combination with the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (\fICURLOPT_SSL_VERIFYPEER(3)\fP has to be set too for the check to fail). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. This option is an alternative to \fICURLOPT_ISSUERCERT(3)\fP which instead expects a filename as input. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf extern char certificateData; extern size_t filesize; int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); blob.data = certificateData; blob.len = filesize; blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_ISSUERCERT_BLOB, &blob); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CRLFILE (3), .BR CURLOPT_ISSUERCERT (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.51 KB	2025-07-08 09:41
📄 CURLOPT_KEEP_SENDING_ON_ERROR.3 .\" generated by cd2nroff 0.1 from CURLOPT_KEEP_SENDING_ON_ERROR.md .TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "2025-06-27" libcurl .SH NAME CURLOPT_KEEP_SENDING_ON_ERROR \- keep sending on early HTTP response >= 300 .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_KEEP_SENDING_ON_ERROR, long keep_sending); .fi .SH DESCRIPTION A long parameter set to 1 tells the library to keep sending the request body if the HTTP code returned is equal to or larger than 300. The default action would be to stop sending and close the stream or connection. This option is suitable for manual NTLM authentication, i.e. if an application does not use \fICURLOPT_HTTPAUTH(3)\fP, but instead sets "Authorization: NTLM ..." headers manually using \fICURLOPT_HTTPHEADER(3)\fP. Most applications do not need this option. .SH DEFAULT 0, stop sending on error .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "sending data"); curl_easy_setopt(curl, CURLOPT_KEEP_SENDING_ON_ERROR, 1L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.51.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RESPONSE_CODE (3), .BR CURLOPT_FAILONERROR (3), .BR CURLOPT_HTTPHEADER (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_KEYPASSWD.3 .\" generated by cd2nroff 0.1 from CURLOPT_KEYPASSWD.md .TH CURLOPT_KEYPASSWD 3 "2025-06-27" libcurl .SH NAME CURLOPT_KEYPASSWD \- passphrase to private key .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_KEYPASSWD, char pwd); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It is used as the password required to use the \fICURLOPT_SSLKEY(3)\fP or \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP private key. You never need a passphrase to load a certificate but you need one to load your private key. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "superman"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and CURLOPT_SSLCERTPASSWD up to 7.9.2. .SH AVAILABILITY Added in curl 7.17.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_PRIVATE_KEYFILE (3), .BR CURLOPT_SSLKEY (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_KRBLEVEL.3 .\" generated by cd2nroff 0.1 from CURLOPT_KRBLEVEL.md .TH CURLOPT_KRBLEVEL 3 "2025-06-27" libcurl .SH NAME CURLOPT_KRBLEVEL \- FTP kerberos security level .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_KRBLEVEL, char level); .fi .SH DESCRIPTION Pass a char pointer as parameter. Set the kerberos security level for FTP; this also enables kerberos awareness. This is a string that should match one of the following: &\(aqclear\(aq, &\(aqsafe\(aq, &\(aqconfidential\(aq or &\(aqprivate\(aq. If the string is set but does not match one of these, \(aqprivate\(aq is used. Set the string to NULL to disable kerberos support for FTP. The application does not have to keep the string around after setting this option. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_KRBLEVEL, "private"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option was known as CURLOPT_KRB4LEVEL up to 7.16.3 .SH AVAILABILITY Added in curl 7.16.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_KRBLEVEL (3), .BR CURLOPT_USE_SSL (3)	1.53 KB	2025-07-08 09:41
📄 CURLOPT_LOCALPORT.3 .\" generated by cd2nroff 0.1 from CURLOPT_LOCALPORT.md .TH CURLOPT_LOCALPORT 3 "2025-06-27" libcurl .SH NAME CURLOPT_LOCALPORT \- local port number to use for socket .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_LOCALPORT, long port); .fi .SH DESCRIPTION Pass a long. This sets the local port number of the socket used for the connection. This can be used in combination with \fICURLOPT_INTERFACE(3)\fP and you are recommended to use \fICURLOPT_LOCALPORTRANGE(3)\fP as well when this option is set. Valid port numbers are 1 \- 65535. .SH DEFAULT 0, disabled \- use whatever the system thinks is fine .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); /* and try 20 more ports following that */ curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_LOCAL_PORT (3), .BR CURLOPT_INTERFACE (3), .BR CURLOPT_LOCALPORTRANGE (3)	1.41 KB	2025-07-08 09:41
📄 CURLOPT_LOCALPORTRANGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_LOCALPORTRANGE.md .TH CURLOPT_LOCALPORTRANGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_LOCALPORTRANGE \- number of additional local ports to try .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_LOCALPORTRANGE, long range); .fi .SH DESCRIPTION Pass a long. The \fIrange\fP argument is the number of attempts libcurl makes to find a working local port number. It starts with the given \fICURLOPT_LOCALPORT(3)\fP and adds one to the number for each retry. Setting this option to 1 or below makes libcurl only do one try for the exact port number. Port numbers by nature are scarce resources that are busy at times so setting this value to something too low might cause unnecessary connection setup failures. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_LOCALPORT, 49152L); /* and try 20 more ports following that */ curl_easy_setopt(curl, CURLOPT_LOCALPORTRANGE, 20L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INTERFACE (3), .BR CURLOPT_LOCALPORT (3)	1.55 KB	2025-07-08 09:41
📄 CURLOPT_LOGIN_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_LOGIN_OPTIONS.md .TH CURLOPT_LOGIN_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_LOGIN_OPTIONS \- login options .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_LOGIN_OPTIONS, char options); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated \fIoptions\fP string to use for the transfer. For more information about the login options please see RFC 2384, RFC 5092 and the IETF draft \fBdraft\-earhart\-url\-smtp\-00.txt\fP. \fICURLOPT_LOGIN_OPTIONS(3)\fP can be used to set protocol specific login options, such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=", and should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP option. Since 8.2.0, IMAP supports the login option "AUTH=+LOGIN". With this option, curl uses the plain (not SASL) LOGIN IMAP command even if the server advertises SASL authentication. Care should be taken in using this option, as it sends your password in plain text. This does not work if the IMAP server disables the plain LOGIN (e.g. to prevent password snooping). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects imap, ldap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_LOGIN_OPTIONS, "AUTH=*"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY Support for OpenLDAP added in 7.82.0. .SH AVAILABILITY Added in curl 7.34.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PASSWORD (3), .BR CURLOPT_USERNAME (3)	2.05 KB	2025-07-08 09:41
📄 CURLOPT_LOW_SPEED_LIMIT.3 .\" generated by cd2nroff 0.1 from CURLOPT_LOW_SPEED_LIMIT.md .TH CURLOPT_LOW_SPEED_LIMIT 3 "2025-06-27" libcurl .SH NAME CURLOPT_LOW_SPEED_LIMIT \- low speed limit in bytes per second .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_LOW_SPEED_LIMIT, long speedlimit); .fi .SH DESCRIPTION Pass a long as parameter. It contains the average transfer speed in bytes per second that the transfer should be below during \fICURLOPT_LOW_SPEED_TIME(3)\fP seconds for libcurl to consider it to be too slow and abort. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* abort if slower than 30 bytes/sec during 60 seconds / curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); res = curl_easy_perform(curl); if(CURLE_OPERATION_TIMEDOUT == res) { printf("Timeout.\\n"); } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_TIME (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_MAX_SEND_SPEED_LARGE (3), .BR CURLOPT_TIMEOUT (3)	1.52 KB	2025-07-08 09:41
📄 CURLOPT_LOW_SPEED_TIME.3 .\" generated by cd2nroff 0.1 from CURLOPT_LOW_SPEED_TIME.md .TH CURLOPT_LOW_SPEED_TIME 3 "2025-06-27" libcurl .SH NAME CURLOPT_LOW_SPEED_TIME \- low speed limit time period .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_LOW_SPEED_TIME, long speedtime); .fi .SH DESCRIPTION Pass a long as parameter. It contains the time in number seconds that the transfer speed should be below the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP for the library to consider it too slow and abort. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* abort if slower than 30 bytes/sec during 60 seconds / curl_easy_setopt(curl, CURLOPT_LOW_SPEED_TIME, 60L); curl_easy_setopt(curl, CURLOPT_LOW_SPEED_LIMIT, 30L); res = curl_easy_perform(curl); if(CURLE_OPERATION_TIMEDOUT == res) { printf("Timeout.\\n"); } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TIMEOUT (3)	1.4 KB	2025-07-08 09:41
📄 CURLOPT_MAIL_AUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAIL_AUTH.md .TH CURLOPT_MAIL_AUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAIL_AUTH \- SMTP authentication address .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAIL_AUTH, char auth); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. This is used to specify the authentication address (identity) of a submitted message that is being relayed to another server. This optional parameter allows co\-operating agents in a trusted environment to communicate the authentication of individual messages and should only be used by the application program, using libcurl, if the application is itself a mail server acting in such an environment. If the application is operating as such and the AUTH address is not known or is invalid, then an empty string should be used for this parameter. Unlike \fICURLOPT_MAIL_FROM(3)\fP and \fICURLOPT_MAIL_RCPT(3)\fP, the address should not be specified within a pair of angled brackets (<>). However, if an empty string is used then a pair of brackets are sent by libcurl as required by RFC 2554. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects smtp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_MAIL_AUTH, "<secret@cave>"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.25.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_FROM (3), .BR CURLOPT_MAIL_RCPT (3)	1.98 KB	2025-07-08 09:41
📄 CURLOPT_MAIL_FROM.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAIL_FROM.md .TH CURLOPT_MAIL_FROM 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAIL_FROM \- SMTP sender address .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAIL_FROM, char from); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. This should be used to specify the sender\(aqs email address when sending SMTP mail with libcurl. An originator email address should be specified with angled brackets (<>) around it, which if not specified are added automatically. If this parameter is not specified then an empty address is sent to the SMTP server which might cause the email to be rejected. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT blank .SH PROTOCOLS This functionality affects smtp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_MAIL_FROM, "president@example.com"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_AUTH (3), .BR CURLOPT_MAIL_RCPT (3)	1.55 KB	2025-07-08 09:41
📄 CURLOPT_MAIL_RCPT.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAIL_RCPT.md .TH CURLOPT_MAIL_RCPT 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAIL_RCPT \- list of SMTP mail recipients .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAIL_RCPT, struct curl_slist rcpts); .fi .SH DESCRIPTION Pass a pointer to a linked list of recipients to pass to the server in your SMTP mail request. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. When performing a mail transfer, each recipient should be specified within a pair of angled brackets (<>), however, should you not use an angled bracket as the first character libcurl assumes you provided a single email address and encloses that address within brackets for you. When performing an address verification (\fBVRFY\fP command), each recipient should be specified as the username or username plus domain (as per Section 3.5 of RFC 5321). When performing a mailing list expand (\fBEXPN\fP command), each recipient should be specified using the mailing list name, such as \fIFriends\fP or \fILondon\-Office\fP. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects smtp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_slist list; list = curl_slist_append(NULL, "root@localhost"); list = curl_slist_append(list, "person@example.com"); curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, list); res = curl_easy_perform(curl); curl_slist_free_all(list); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_AUTH (3), .BR CURLOPT_MAIL_FROM (3)	2.26 KB	2025-07-08 09:41
📄 CURLOPT_MAIL_RCPT_ALLOWFAILS.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAIL_RCPT_ALLOWFAILS.md .TH CURLOPT_MAIL_RCPT_ALLOWFAILS 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAIL_RCPT_ALLOWFAILS \- allow RCPT TO command to fail for some recipients .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAIL_RCPT_ALLOWFAILS, long allow); .fi .SH DESCRIPTION If \fIallow\fP is set to 1L, allow RCPT TO command to fail for some recipients. When sending data to multiple recipients, by default curl aborts the SMTP conversation if either one of the recipients causes the RCPT TO command to return an error. The default behavior can be changed by setting \fIallow\fP to 1L which makes libcurl ignore errors for individual recipients and proceed with the remaining accepted recipients. If all recipients trigger RCPT TO failures and this flag is specified, curl aborts the SMTP conversation and returns the error received from to the last RCPT TO command. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects smtp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { struct curl_slist list; CURLcode res; / Adding one valid and one invalid email address */ list = curl_slist_append(NULL, "person@example.com"); list = curl_slist_append(list, "invalidemailaddress"); curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_MAIL_RCPT_ALLOWFAILS, 1L); res = curl_easy_perform(curl); curl_slist_free_all(list); curl_easy_cleanup(curl); } } .fi .SH HISTORY This option was called CURLOPT_MAIL_RCPT_ALLLOWFAILS (with three instead of two letter L) before 8.2.0 .SH AVAILABILITY Added in curl 8.2.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_FROM (3), .BR CURLOPT_MAIL_RCPT (3)	1.95 KB	2025-07-08 09:41
📄 CURLOPT_MAXAGE_CONN.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXAGE_CONN.md .TH CURLOPT_MAXAGE_CONN 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXAGE_CONN \- max idle time allowed for reusing a connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXAGE_CONN, long age); .fi .SH DESCRIPTION Pass a long as parameter containing \fIage\fP \- the maximum time in seconds allowed for an existing connection to have been idle to be considered for reuse for this request. The "connection cache" holds previously used connections. When a new request is to be done, libcurl considers any connection that matches for reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too old connections for reuse, since old connections have a higher risk of not working and thus trying them is a performance loss and sometimes service loss due to the difficulties to figure out the situation. If a connection is found in the cache that is older than this set \fIage\fP, it is closed instead. .SH DEFAULT 118 seconds .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* only allow 30 seconds idle time */ curl_easy_setopt(curl, CURLOPT_MAXAGE_CONN, 30L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.65.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FORBID_REUSE (3), .BR CURLOPT_FRESH_CONNECT (3), .BR CURLOPT_MAXLIFETIME_CONN (3), .BR CURLOPT_TIMEOUT (3)	1.71 KB	2025-07-08 09:41
📄 CURLOPT_MAXCONNECTS.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXCONNECTS.md .TH CURLOPT_MAXCONNECTS 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXCONNECTS \- maximum connection cache size .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXCONNECTS, long amount); .fi .SH DESCRIPTION Pass a long. The set \fIamount\fP is the maximum number of connections that libcurl may keep alive in its connection cache after use. The default is 5, and there is not much point in changing this value unless you are perfectly aware of how this works. This concerns connections using any of the protocols that support persistent connections. When reaching the maximum limit, curl closes the oldest connection present in the cache to prevent the number of connections from increasing. If you already have performed transfers with this curl handle, setting a smaller \fICURLOPT_MAXCONNECTS(3)\fP than before may cause open connections to get closed unnecessarily. If you add this easy handle to a multi handle, this setting is not acknowledged, and you must instead use \fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_MAXCONNECTS(3)\fP option. .SH DEFAULT 5 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* limit the connection cache for this handle to no more than 3 */ curl_easy_setopt(curl, CURLOPT_MAXCONNECTS, 3L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAXCONNECTS (3), .BR CURLMOPT_MAX_HOST_CONNECTIONS (3), .BR CURLMOPT_MAX_TOTAL_CONNECTIONS (3), .BR CURLOPT_MAXREDIRS (3)	1.89 KB	2025-07-08 09:41
📄 CURLOPT_MAXFILESIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXFILESIZE.md .TH CURLOPT_MAXFILESIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXFILESIZE \- maximum file size allowed to download .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXFILESIZE, long size); .fi .SH DESCRIPTION Pass a long as parameter. This specifies the maximum accepted \fIsize\fP (in bytes) of a file to download. If the file requested is found larger than this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned. Passing a zero \fIsize\fP disables this, and passing a negative \fIsize\fP yields a \fICURLE_BAD_FUNCTION_ARGUMENT\fP. The file size is not always known prior to the download start, and for such transfers this option has no effect \- even if the file transfer eventually ends up being larger than this given limit. If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. Since 8.4.0, this option also stops ongoing transfers if they reach this threshold. .SH DEFAULT 0, meaning disabled. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* refuse to download if larger than 1000 bytes */ curl_easy_setopt(curl, CURLOPT_MAXFILESIZE, 1000L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.8 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAXFILESIZE_LARGE (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3)	1.71 KB	2025-07-08 09:41
📄 CURLOPT_MAXFILESIZE_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXFILESIZE_LARGE.md .TH CURLOPT_MAXFILESIZE_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXFILESIZE_LARGE, curl_off_t size); .fi .SH DESCRIPTION Pass a curl_off_t as parameter. This specifies the maximum accepted \fIsize\fP (in bytes) of a file to download. If the file requested is found larger than this value, the transfer is aborted and \fICURLE_FILESIZE_EXCEEDED\fP is returned. Passing a zero \fIsize\fP disables this, and passing a negative \fIsize\fP yields a \fICURLE_BAD_FUNCTION_ARGUMENT\fP. The file size is not always known prior to the download start, and for such transfers this option has no effect \- even if the file transfer eventually ends up being larger than this given limit. Since 8.4.0, this option also stops ongoing transfers if they reach this threshold. .SH DEFAULT 0, meaning disabled. .SH PROTOCOLS This functionality affects ftp, http and mqtt .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_off_t ridiculous = (curl_off_t)1 << 48; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* refuse to download if larger than ridiculous */ curl_easy_setopt(curl, CURLOPT_MAXFILESIZE_LARGE, ridiculous); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.11.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAXFILESIZE (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_MAXLIFETIME_CONN.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXLIFETIME_CONN.md .TH CURLOPT_MAXLIFETIME_CONN 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXLIFETIME_CONN \- max lifetime (since creation) allowed for reusing a connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXLIFETIME_CONN, long maxlifetime); .fi .SH DESCRIPTION Pass a long as parameter containing \fImaxlifetime\fP \- the maximum time in seconds, since the creation of the connection, that you allow an existing connection to have to be considered for reuse for this request. libcurl features a connection cache that holds previously used connections. When a new request is to be done, libcurl considers any connection that matches for reuse. The \fICURLOPT_MAXLIFETIME_CONN(3)\fP limit prevents libcurl from trying too old connections for reuse. This can be used for client\-side load balancing. If a connection is found in the cache that is older than this set \fImaxlifetime\fP, it is instead marked for closure. If set to 0, this behavior is disabled: all connections are eligible for reuse. .SH DEFAULT 0 seconds (i.e., disabled) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* only allow each connection to be reused for 30 seconds */ curl_easy_setopt(curl, CURLOPT_MAXLIFETIME_CONN, 30L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.80.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FORBID_REUSE (3), .BR CURLOPT_FRESH_CONNECT (3), .BR CURLOPT_MAXAGE_CONN (3), .BR CURLOPT_TIMEOUT (3)	1.85 KB	2025-07-08 09:41
📄 CURLOPT_MAXREDIRS.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAXREDIRS.md .TH CURLOPT_MAXREDIRS 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAXREDIRS \- maximum number of redirects allowed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAXREDIRS, long amount); .fi .SH DESCRIPTION Pass a long. The set number is the redirection limit \fIamount\fP. If that many redirections have been followed, the next redirect triggers the error (\fICURLE_TOO_MANY_REDIRECTS\fP). This option only makes sense if the \fICURLOPT_FOLLOWLOCATION(3)\fP is used at the same time. Setting the limit to 0 makes libcurl refuse any redirect. Set it to \-1 for an infinite number of redirects. This allows your application to get stuck in never\-ending redirect loops. .SH DEFAULT 30 (since 8.3.0), it was previously unlimited. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* enable redirect following / curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); / allow three redirects / curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLINFO_REDIRECT_URL (3), .BR CURLOPT_FOLLOWLOCATION (3)	1.57 KB	2025-07-08 09:41
📄 CURLOPT_MAX_RECV_SPEED_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAX_RECV_SPEED_LARGE.md .TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAX_RECV_SPEED_LARGE, curl_off_t maxspeed); .fi .SH DESCRIPTION Pass a curl_off_t as parameter. If a download exceeds this \fImaxspeed\fP (counted in bytes per second) the transfer pauses to keep the average speed less than or equal to the parameter value. Defaults to unlimited speed. This is not an exact science. libcurl attempts to keep the average speed below the given threshold over a period time. If you set \fImaxspeed\fP to a value lower than \fICURLOPT_BUFFERSIZE(3)\fP, libcurl might download faster than the set limit initially. This option does not affect transfer speeds done with FILE:// URLs. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* cap the download speed to 31415 bytes/sec */ curl_easy_setopt(curl, CURLOPT_MAX_RECV_SPEED_LARGE, (curl_off_t)31415); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAX_SEND_SPEED_LARGE (3), .BR CURLOPT_TIMEOUT (3)	1.65 KB	2025-07-08 09:41
📄 CURLOPT_MAX_SEND_SPEED_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_MAX_SEND_SPEED_LARGE.md .TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MAX_SEND_SPEED_LARGE, curl_off_t maxspeed); .fi .SH DESCRIPTION Pass a curl_off_t as parameter with the \fImaxspeed\fP. If an upload exceeds this speed (counted in bytes per second) the transfer pauses to keep the average speed less than or equal to the parameter value. Defaults to unlimited speed. This is not an exact science. libcurl attempts to keep the average speed below the given threshold over a period time. If you set \fImaxspeed\fP to a value lower than \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP, libcurl might "shoot over" the limit on its first send and still send off a full buffer. This option does not affect transfer speeds done with FILE:// URLs. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* cap the upload speed to 1000 bytes/sec / curl_easy_setopt(curl, CURLOPT_MAX_SEND_SPEED_LARGE, (curl_off_t)1000); / (set some upload options as well) */ ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3)	1.71 KB	2025-07-08 09:41
📄 CURLOPT_MIMEPOST.3 .\" generated by cd2nroff 0.1 from CURLOPT_MIMEPOST.md .TH CURLOPT_MIMEPOST 3 "2025-06-27" libcurl .SH NAME CURLOPT_MIMEPOST \- send data from mime structure .SH SYNOPSIS .nf #include <curl/curl.h> curl_mime mime; CURLcode curl_easy_setopt(CURL handle, CURLOPT_MIMEPOST, mime); .fi .SH DESCRIPTION Pass a mime handle previously obtained from \fIcurl_mime_init(3)\fP. This setting is supported by the HTTP protocol to post forms and by the SMTP and IMAP protocols to provide the email data to send/upload. This option is the preferred way of posting an HTTP form, replacing and extending the \fICURLOPT_HTTPPOST(3)\fP option. When setting \fICURLOPT_MIMEPOST(3)\fP to NULL, libcurl resets the request type for HTTP to the default to disable the POST. Typically that would mean it is reset to GET. Instead you should set a desired request method explicitly. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_mime multipart = curl_mime_init(curl); if(multipart) { curl_mimepart part = curl_mime_addpart(multipart); curl_mime_name(part, "name"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); part = curl_mime_addpart(multipart); curl_mime_name(part, "project"); curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); part = curl_mime_addpart(multipart); curl_mime_name(part, "logotype-image"); curl_mime_filedata(part, "curl.png"); / Set the form info / curl_easy_setopt(curl, CURLOPT_MIMEPOST, multipart); curl_easy_perform(curl); / post away / curl_mime_free(multipart); / free the post data */ } } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HTTPPOST (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_PUT (3), .BR curl_mime_init (3)	1.86 KB	2025-07-08 09:41
📄 CURLOPT_MIME_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_MIME_OPTIONS.md .TH CURLOPT_MIME_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_MIME_OPTIONS \- set MIME option flags .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_MIME_OPTIONS, long options); .fi .SH DESCRIPTION Pass a long that holds a bitmask of options. Each bit is a boolean flag used while encoding a MIME tree or multipart form data. Available bits are: .IP CURLMIMEOPT_FORMESCAPE Tells libcurl to escape multipart form field and filenames using the backslash\-escaping algorithm rather than percent\-encoding (HTTP only). Backslash\-escaping consists in preceding backslashes and double quotes with a backslash. Percent encoding maps all occurrences of double quote, carriage return and line feed to %22, %0D and %0A respectively. Before version 7.81.0, percent\-encoding was never applied. HTTP browsers used to do backslash\-escaping in the past but have over time transitioned to use percent\-encoding. This option allows one to address server\-side applications that have not yet have been converted. As an example, consider field or filename \fIstrangename"kind\fP. When the containing multipart form is sent, this is normally transmitted as \fIstrangename%22kind\fP. When this option is set, it is sent as \fIstrangename"kind\fP. .SH DEFAULT 0, meaning disabled. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); curl_mime form = NULL; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_MIME_OPTIONS, (long)CURLMIMEOPT_FORMESCAPE); form = curl_mime_init(curl); if(form) { curl_mimepart part = curl_mime_addpart(form); if(part) { curl_mime_filedata(part, "strange\\\\file\\\\name"); curl_mime_name(part, "strange\\"field\\"name"); curl_easy_setopt(curl, CURLOPT_MIMEPOST, form); /* Perform the request */ curl_easy_perform(curl); } } curl_easy_cleanup(curl); curl_mime_free(form); } } .fi .SH AVAILABILITY Added in curl 7.81.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPOST (3), .BR CURLOPT_MIMEPOST (3)	2.36 KB	2025-07-08 09:41
📄 CURLOPT_NETRC.3 .\" generated by cd2nroff 0.1 from CURLOPT_NETRC.md .TH CURLOPT_NETRC 3 "2025-06-27" libcurl .SH NAME CURLOPT_NETRC \- enable use of .netrc .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NETRC, long level); .fi .SH DESCRIPTION This parameter controls the preference \fIlevel\fP of libcurl between using usernames and passwords from your \fI~/.netrc\fP file, relative to usernames and passwords in the URL supplied with \fICURLOPT_URL(3)\fP. On Windows, libcurl primarily checks for \fI.netrc\fP in \fI%HOME%\fP. If \fI%HOME%\fP is not set on Windows, libcurl falls back to \fI%USERPROFILE%\fP. If the file does not exist, it falls back to check if there is instead a file named \fI_netrc\fP \- using an underscore instead of period. You can also tell libcurl a different filename to use with \fICURLOPT_NETRC_FILE(3)\fP. libcurl uses a username (and supplied or prompted password) supplied with \fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP in preference to any of the options controlled by this parameter. Only machine name, username and password are taken into account (init macros and similar things are not supported). libcurl does not verify that the file has the correct properties set (as the standard Unix ftp client does). It should only be readable by user. \fIlevel\fP is a long that should be set to one of the values described below. .IP "CURL_NETRC_IGNORED (0)" libcurl ignores the \fI.netrc\fP file. This is the default. .IP "CURL_NETRC_OPTIONAL (1)" The use of the \fI.netrc\fP file is optional, and information in the URL is to be preferred. The file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that \fImachine\fP, which ever information is not specified. .IP "CURL_NETRC_REQUIRED (2)" The use of the \fI.netrc\fP file is required, and any credential information present in the URL is ignored. The file is scanned for the host and username (to find the password only) or for the host only, to find the first username and password after that \fImachine\fP, which ever information is not specified. .SH FILE FORMAT The \fB.netrc\fP file format is simple: you specify lines with a machine name and follow the login and password that are associated with that machine. Each field is provided as a sequence of letters that ends with a space or newline. Starting in 7.84.0, libcurl also supports quoted strings. They start and end with double quotes and support the escaped special letters ", n, r, and t. Quoted strings are the only way a space character can be used in a username or password. .IP "machine \<name\>" Provides credentials for a host called \fBname\fP. libcurl searches the .netrc file for a machine token that matches the hostname specified in the URL. Once a match is made, the subsequent tokens are processed, stopping when the end of file is reached or another "machine" is encountered. .IP default This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. To provide a default anonymous login for hosts that are not otherwise matched, add a line similar to this in the end: .nf default login anonymous password user@domain .fi .IP "login \<name\>" The username string for the remote machine. .IP "password \<secret\>" Supply a password. If this token is present, curl supplies the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file you really should make sure the file is not readable by anyone besides the user. .IP "macdef \<name\>" Define a macro. This feature is not supported by libcurl. In order for the rest of the .netrc to still work fine, libcurl properly skips every definition done with "macdef" that it finds. .SH DEFAULT CURL_NETRC_IGNORED .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NETRC_FILE (3), .BR CURLOPT_USERNAME (3), .BR CURLOPT_USERPWD (3)	4.46 KB	2025-07-08 09:41
📄 CURLOPT_NETRC_FILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_NETRC_FILE.md .TH CURLOPT_NETRC_FILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_NETRC_FILE \- filename to read .netrc info from .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NETRC_FILE, char file); .fi .SH DESCRIPTION Pass a char pointer as parameter, pointing to a null\-terminated string containing the full path name to the \fIfile\fP you want libcurl to use as .netrc file. If this option is omitted, and \fICURLOPT_NETRC(3)\fP is set, libcurl checks for a .netrc file in the current user\(aqs home directory. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/"); curl_easy_setopt(curl, CURLOPT_NETRC, CURL_NETRC_OPTIONAL); curl_easy_setopt(curl, CURLOPT_NETRC_FILE, "/tmp/magic-netrc"); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.11.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NETRC (3), .BR CURLOPT_PASSWORD (3), .BR CURLOPT_USERNAME (3)	1.51 KB	2025-07-08 09:41
📄 CURLOPT_NEW_DIRECTORY_PERMS.3 .\" generated by cd2nroff 0.1 from CURLOPT_NEW_DIRECTORY_PERMS.md .TH CURLOPT_NEW_DIRECTORY_PERMS 3 "2025-06-27" libcurl .SH NAME CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NEW_DIRECTORY_PERMS, long mode); .fi .SH DESCRIPTION Pass a long as a parameter, containing the value of the permissions that is set on newly created directories on the remote server. The default value is \fI0755\fP, but any valid value can be used. The only protocols that can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. .SH DEFAULT 0755 .SH PROTOCOLS This functionality affects file, scp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/newdir/file.zip"); curl_easy_setopt(curl, CURLOPT_FTP_CREATE_MISSING_DIRS, 1L); curl_easy_setopt(curl, CURLOPT_NEW_DIRECTORY_PERMS, 0644L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FTP_CREATE_MISSING_DIRS (3), .BR CURLOPT_NEW_FILE_PERMS (3), .BR CURLOPT_UPLOAD (3)	1.42 KB	2025-07-08 09:41
📄 CURLOPT_NEW_FILE_PERMS.3 .\" generated by cd2nroff 0.1 from CURLOPT_NEW_FILE_PERMS.md .TH CURLOPT_NEW_FILE_PERMS 3 "2025-06-27" libcurl .SH NAME CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NEW_FILE_PERMS, long mode); .fi .SH DESCRIPTION Pass a long as a parameter, containing the value of the permissions that are set on newly created files on the remote server. The default value is \fI0644\fP. The only protocols that can use this are \fIsftp://\fP, \fIscp://\fP, and \fIfile://\fP. .SH DEFAULT 0644 .SH PROTOCOLS This functionality affects file, scp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "sftp://upload.example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_NEW_FILE_PERMS, 0664L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NEW_DIRECTORY_PERMS (3), .BR CURLOPT_UPLOAD (3)	1.23 KB	2025-07-08 09:41
📄 CURLOPT_NOBODY.3 .\" generated by cd2nroff 0.1 from CURLOPT_NOBODY.md .TH CURLOPT_NOBODY 3 "2025-06-27" libcurl .SH NAME CURLOPT_NOBODY \- do the download request without getting the body .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NOBODY, long opt); .fi .SH DESCRIPTION A long parameter set to 1 tells libcurl to not include the body\-part in the output when doing what would otherwise be a download. For HTTP(S), this makes libcurl do a HEAD request. For most other protocols it means just not asking to transfer the body data. For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, disabling this option (with 0) makes it a GET again \- only if the method is still set to be HEAD. The proper way to get back to a GET request is to set \fICURLOPT_HTTPGET(3)\fP and for other methods, use the POST or UPLOAD options. Enabling \fICURLOPT_NOBODY(3)\fP means asking for a download without a body. If you do a transfer with HTTP that involves a method other than HEAD, you get a body (unless the resource and server sends a zero byte body for the specific URL you request). .SH DEFAULT 0, the body is transferred .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* get us the resource without a body - use HEAD / curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPGET (3), .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_REQUEST_TARGET (3), .BR CURLOPT_UPLOAD (3)	1.86 KB	2025-07-08 09:41
📄 CURLOPT_NOPROGRESS.3 .\" generated by cd2nroff 0.1 from CURLOPT_NOPROGRESS.md .TH CURLOPT_NOPROGRESS 3 "2025-06-27" libcurl .SH NAME CURLOPT_NOPROGRESS \- switch off the progress meter .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NOPROGRESS, long onoff); .fi .SH DESCRIPTION If \fIonoff\fP is to 1, it tells the library to shut off the progress meter completely for requests done with this \fIhandle\fP. It also prevents the \fICURLOPT_XFERINFOFUNCTION(3)\fP or \fICURLOPT_PROGRESSFUNCTION(3)\fP from getting called. .SH DEFAULT 1, meaning it normally runs without a progress meter. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable progress meter / curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_PROGRESSFUNCTION (3), .BR CURLOPT_VERBOSE (3), .BR CURLOPT_XFERINFOFUNCTION (3)	1.3 KB	2025-07-08 09:41
📄 CURLOPT_NOPROXY.3 .\" generated by cd2nroff 0.1 from CURLOPT_NOPROXY.md .TH CURLOPT_NOPROXY 3 "2025-06-27" libcurl .SH NAME CURLOPT_NOPROXY \- disable proxy use for specific hosts .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NOPROXY, char noproxy); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string. The string consists of a comma separated list of hostnames that do not require a proxy to get reached, even if one is specified. The only wildcard available is a single * character, which matches all hosts, and effectively disables the proxy. Each name in this list is matched as either a domain which contains the hostname, or the hostname itself. For example, "ample.com" would match ample.com, ample.com:80, and www.ample.com, but not www.example.com or ample.com.org. Setting the \fInoproxy\fP string to "" (an empty string) explicitly enables the proxy for all hostnames, even if there is an environment variable set for it. Enter IPv6 numerical addresses in the list of hostnames without enclosing brackets: .nf "example.com,::1,localhost" .fi Since 7.86.0, IP addresses specified to this option can be provided using CIDR notation: an appended slash and number specifies the number of "network bits" out of the address to use in the comparison. For example "192.168.0.0/16" would match all addresses starting with "192.168". The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH Environment variables If there is an environment variable called \fBno_proxy\fP (or \fBNO_PROXY\fP), it is used if the \fICURLOPT_NOPROXY(3)\fP option is not set. It works exactly the same way. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { / accept various URLs / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / use this proxy / curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); / ... but make sure this host name is not proxied */ curl_easy_setopt(curl, CURLOPT_NOPROXY, "www.example.com"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_PROXYTYPE (3)	2.55 KB	2025-07-08 09:41
📄 CURLOPT_NOSIGNAL.3 .\" generated by cd2nroff 0.1 from CURLOPT_NOSIGNAL.md .TH CURLOPT_NOSIGNAL 3 "2025-06-27" libcurl .SH NAME CURLOPT_NOSIGNAL \- skip all signal handling .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_NOSIGNAL, long onoff); .fi .SH DESCRIPTION If \fIonoff\fP is 1, libcurl uses no functions that install signal handlers or any functions that cause signals to be sent to the process. This option is here to allow multi\-threaded Unix applications to still set/use all timeout options etc, without risking getting signals. If this option is set and libcurl has been built with the standard name resolver, timeouts cannot occur while the name resolve takes place. Consider building libcurl with the c\-ares or threaded resolver backends to enable asynchronous DNS lookups, to enable timeouts for name resolves without the use of signals. Setting \fICURLOPT_NOSIGNAL(3)\fP to 1 makes libcurl NOT ask the system to ignore SIGPIPE signals, which otherwise are sent by the system when trying to send data to a socket which is closed in the other end. libcurl makes an effort to never cause such SIGPIPE signals to trigger, but some operating systems have no way to avoid them and even on those that have there are some corner cases when they may still happen, contrary to our desire. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TIMEOUT (3)	1.91 KB	2025-07-08 09:41
📄 CURLOPT_OPENSOCKETDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_OPENSOCKETDATA.md .TH CURLOPT_OPENSOCKETDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_OPENSOCKETDATA \- pointer passed to open socket callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_OPENSOCKETDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the open socket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf /* make libcurl use the already established socket 'sockfd' / static curl_socket_t opensocket(void clientp, curlsocktype purpose, struct curl_sockaddr address) { curl_socket_t sockfd; sockfd = (curl_socket_t )clientp; / the actual externally set socket is passed in via the OPENSOCKETDATA option / return sockfd; } static int sockopt_callback(void clientp, curl_socket_t curlfd, curlsocktype purpose) { /* This return code was added in libcurl 7.21.5 / return CURL_SOCKOPT_ALREADY_CONNECTED; } int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; extern int sockfd; /* the already connected one / / libcurl thinks that you connect to the host * and port that you specify in the URL option. / curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); / call this function to get a socket / curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); / call this function to set options for the socket */ curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.17.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CLOSESOCKETFUNCTION (3), .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR CURLOPT_SOCKOPTFUNCTION (3)	2.19 KB	2025-07-08 09:41
📄 CURLOPT_OPENSOCKETFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_OPENSOCKETFUNCTION.md .TH CURLOPT_OPENSOCKETFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_OPENSOCKETFUNCTION \- callback for opening socket .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection / } curlsocktype; struct curl_sockaddr { int family; int socktype; int protocol; unsigned int addrlen; struct sockaddr addr; }; curl_socket_t opensocket_callback(void clientp, curlsocktype purpose, struct curl_sockaddr address); CURLcode curl_easy_setopt(CURL handle, CURLOPT_OPENSOCKETFUNCTION, opensocket_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl instead of the \fIsocket(2)\fP call. The callback\(aqs \fIpurpose\fP argument identifies the exact purpose for this particular socket. \fICURLSOCKTYPE_IPCXN\fP is for IP based connections and is the only purpose currently used in libcurl. Future versions of libcurl may support more purposes. The \fIclientp\fP pointer contains whatever user\-defined value set using the \fICURLOPT_OPENSOCKETDATA(3)\fP function. The callback gets the resolved peer address as the \fIaddress\fP argument and is allowed to modify the address or refuse to connect completely. The callback function should return the newly created socket or \fICURL_SOCKET_BAD\fP in case no connection could be established or another error was detected. Any additional \fIsetsockopt(2)\fP calls can of course be done on the socket at the user\(aqs discretion. If \fICURL_SOCKET_BAD\fP is returned by the callback then libcurl treats it as a failed connection and tries to open a socket to connect to a different IP address associated with the transfer. If there are no more addresses to try then libcurl fails the transfer with error code \fICURLE_COULDNT_CONNECT\fP. You can get the IP address that curl is opening the socket for by casting \fIaddress\->addr\fP to \fIsockaddr_in\fP if \fIaddress\->family\fP is \fIAF_INET\fP, or to \fIsockaddr_in6\fP if \fIaddress\->family\fP is \fIAF_INET6\fP. For an example of how that data can be compared against refer to \fIdocs/examples/block_ip.c\fP. If you want to pass in a socket with an already established connection, pass the socket back with this callback and then use \fICURLOPT_SOCKOPTFUNCTION(3)\fP to signal that it already is connected. .SH DEFAULT The equivalent of this: .nf return socket(addr->family, addr->socktype, addr->protocol); .fi .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf /* make libcurl use the already established socket 'sockfd' / static curl_socket_t opensocket(void clientp, curlsocktype purpose, struct curl_sockaddr address) { curl_socket_t sockfd; sockfd = (curl_socket_t )clientp; / the actual externally set socket is passed in via the OPENSOCKETDATA option / return sockfd; } static int sockopt_callback(void clientp, curl_socket_t curlfd, curlsocktype purpose) { /* This return code was added in libcurl 7.21.5 / return CURL_SOCKOPT_ALREADY_CONNECTED; } int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; extern int sockfd; /* the already connected one / / libcurl thinks that you connect to the host * and port that you specify in the URL option. / curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); / call this function to get a socket / curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); / call this function to set options for the socket */ curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.17.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CLOSESOCKETFUNCTION (3), .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR CURLOPT_SOCKOPTFUNCTION (3)	4.28 KB	2025-07-08 09:41
📄 CURLOPT_PASSWORD.3 .\" generated by cd2nroff 0.1 from CURLOPT_PASSWORD.md .TH CURLOPT_PASSWORD 3 "2025-06-27" libcurl .SH NAME CURLOPT_PASSWORD \- password to use in authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PASSWORD, char pwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated password to use for the transfer. The \fICURLOPT_PASSWORD(3)\fP option should be used in conjunction with the \fICURLOPT_USERNAME(3)\fP option. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "qwerty"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_USERNAME (3), .BR CURLOPT_USERPWD (3)	1.43 KB	2025-07-08 09:41
📄 CURLOPT_PATH_AS_IS.3 .\" generated by cd2nroff 0.1 from CURLOPT_PATH_AS_IS.md .TH CURLOPT_PATH_AS_IS 3 "2025-06-27" libcurl .SH NAME CURLOPT_PATH_AS_IS \- do not handle dot\-dot sequences .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PATH_AS_IS, long leaveit); .fi .SH DESCRIPTION Set the long \fIleaveit\fP to 1, to explicitly tell libcurl to not alter the given path before passing it on to the server. This instructs libcurl to NOT squash sequences of "/../" or "/./" that may exist in the URL\(aqs path part and that is supposed to be removed according to RFC 3986 section 5.2.4. Some server implementations are known to (erroneously) require the dot\-dot sequences to remain in the path and some clients want to pass these on in order to try out server implementations. By default libcurl normalizes such sequences before using the path. This is a request for the \fIfirst\fP request libcurl issues. When following redirects, it may no longer apply. The corresponding flag for the \fIcurl_url_set(3)\fP function is called \fBCURLU_PATH_AS_IS\fP. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/../../etc/password"); curl_easy_setopt(curl, CURLOPT_PATH_AS_IS, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.42.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_STDERR (3), .BR CURLOPT_URL (3), .BR curl_url_set (3)	1.73 KB	2025-07-08 09:41
📄 CURLOPT_PINNEDPUBLICKEY.3 .\" generated by cd2nroff 0.1 from CURLOPT_PINNEDPUBLICKEY.md .TH CURLOPT_PINNEDPUBLICKEY 3 "2025-06-27" libcurl .SH NAME CURLOPT_PINNEDPUBLICKEY \- pinned public key .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PINNEDPUBLICKEY, char pinnedpubkey); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string can be the filename of your pinned public key. The file format expected is "PEM" or \&"DER". The string can also be any number of base64 encoded sha256 hashes preceded by "sha256//" and separated by ";" When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. A public key is extracted from this certificate and if it does not exactly match the public key provided to this option, curl aborts the connection before sending or receiving any data. This option is independent of option \fICURLOPT_SSL_VERIFYPEER(3)\fP. If you turn off that option then the peer is still verified by public key. On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der"); / OR curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3" "tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEg" "oChTociMee9wno="); / / Perform the request */ curl_easy_perform(curl); } } .fi .SH PUBLIC KEY EXTRACTION If you do not have the server\(aqs public key file you can extract it from the server\(aqs certificate. .nf # retrieve the server's certificate if you do not already have it # # be sure to examine the certificate to see if it is what you expected # # Windows-specific: # - Use NUL instead of /dev/null. # - OpenSSL may wait for input instead of disconnecting. Hit enter. # - If you do not have sed, then just copy the certificate into a file: # Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. # openssl s_client -servername www.example.com -connect www.example.com:443 \\ < /dev/null \| sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem # extract public key in pem format from certificate openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem # convert public key from pem to der openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \\ -out www.example.com.pubkey.der # sha256 hash and base64 encode der to string for use openssl dgst -sha256 -binary www.example.com.pubkey.der \| openssl base64 .fi The public key in PEM format contains a header, base64 data and a footer: .nf -----BEGIN PUBLIC KEY----- [BASE 64 DATA] -----END PUBLIC KEY----- .fi .SH HISTORY .IP "PEM/DER support" 7.39.0: OpenSSL, GnuTLS 7.43.0: wolfSSL 7.47.0: mbedTLS 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ 7.58.1: Schannel .IP "sha256 support" 7.44.0: OpenSSL, GnuTLS and wolfSSL 7.47.0: mbedTLS 7.54.1: Secure Transport on macOS 10.7+/iOS 10+ 7.58.1: Schannel Other SSL backends not supported. .SH AVAILABILITY Added in curl 7.39.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	3.82 KB	2025-07-08 09:41
📄 CURLOPT_PIPEWAIT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PIPEWAIT.md .TH CURLOPT_PIPEWAIT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PIPEWAIT \- wait for multiplexing .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PIPEWAIT, long wait); .fi .SH DESCRIPTION Set \fIwait\fP to 1L to tell libcurl to prefer to wait for a connection to confirm or deny that it can do multiplexing before continuing. When about to perform a new transfer that allows multiplexing, libcurl checks for existing connections to use. If no such connection exists it immediately continues and creates a fresh new connection to use. By setting this option to 1 \- and having \fICURLMOPT_PIPELINING(3)\fP enabled for the multi handle this transfer is associated with \- libcurl instead waits for the connection to reveal if it is possible to multiplex on before it continues. This enables libcurl to much better keep the number of connections to a minimum when using multiplexing protocols. With this option set, libcurl prefers to wait and reuse an existing connection for multiplexing rather than the opposite: prefer to open a new connection rather than waiting. The waiting time is as long as it takes for the connection to get up and for libcurl to get the necessary response back that informs it about its protocol and support level. .SH DEFAULT 0 (off) .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PIPEWAIT, 1L); /* now add this easy handle to the multi handle */ } } .fi .SH AVAILABILITY Added in curl 7.43.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_MAX_HOST_CONNECTIONS (3), .BR CURLMOPT_PIPELINING (3), .BR CURLOPT_FORBID_REUSE (3), .BR CURLOPT_FRESH_CONNECT (3)	1.99 KB	2025-07-08 09:41
📄 CURLOPT_PORT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PORT.md .TH CURLOPT_PORT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PORT \- remote port number to connect to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PORT, long number); .fi .SH DESCRIPTION We discourage using this option since its scope is not obvious and hard to predict. Set the preferred port number in the URL instead. This option sets \fInumber\fP to be the remote port number to connect to, instead of the one specified in the URL or the default port for the used protocol. Usually, you just let the URL decide which port to use but this allows the application to override that. While this option accepts a \(aqlong\(aq, a port number is an unsigned 16 bit number and therefore using a port number lower than zero or over 65535 causes a \fBCURLE_BAD_FUNCTION_ARGUMENT\fP error. .SH DEFAULT 0 which makes it not used. This also makes port number zero impossible to set with this API. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PORT, 8080L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRIMARY_PORT (3), .BR CURLOPT_STDERR (3), .BR CURLOPT_URL (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_POST.3 .\" generated by cd2nroff 0.1 from CURLOPT_POST.md .TH CURLOPT_POST 3 "2025-06-27" libcurl .SH NAME CURLOPT_POST \- make an HTTP POST .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POST, long post); .fi .SH DESCRIPTION A parameter set to 1 tells libcurl to do a regular HTTP post. This also makes libcurl use a "Content\-Type: application/x\-www\-form\-urlencoded" header. This is the most commonly used POST method. Use one of \fICURLOPT_POSTFIELDS(3)\fP or \fICURLOPT_COPYPOSTFIELDS(3)\fP options to specify what data to post and \fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP to set the data size. Optionally, you can provide data to POST using the \fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_READDATA(3)\fP options but then you must make sure to not set \fICURLOPT_POSTFIELDS(3)\fP to anything but NULL. When providing data with a callback, you must transmit it using chunked transfer\-encoding or you must set the size of the data with the \fICURLOPT_POSTFIELDSIZE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP options. To enable chunked encoding, you simply pass in the appropriate Transfer\-Encoding header, see the post\-callback.c example. You can override the default POST Content\-Type: header by setting your own with \fICURLOPT_HTTPHEADER(3)\fP. Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. If you use POST to an HTTP 1.1 server, you can send data without knowing the size before starting the POST if you use chunked encoding. You enable this by adding a header like "Transfer\-Encoding: chunked" with \fICURLOPT_HTTPHEADER(3)\fP. With HTTP 1.0 or without chunked transfer, you must specify the size in the request. (Since 7.66.0, libcurl automatically uses chunked encoding for POSTs if the size is unknown.) When setting \fICURLOPT_POST(3)\fP to 1, libcurl automatically sets \fICURLOPT_NOBODY(3)\fP and \fICURLOPT_HTTPGET(3)\fP to 0. If you issue a POST request and then want to make a HEAD or GET using the same reused handle, you must explicitly set the new request type using \fICURLOPT_NOBODY(3)\fP or \fICURLOPT_HTTPGET(3)\fP or similar. When setting \fICURLOPT_POST(3)\fP to 0, libcurl resets the request type to the default to disable the POST. Typically that means gets reset to GET. Instead you should set a new request type explicitly as described above. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_POST, 1L); /* set up the read callback with CURLOPT_READFUNCTION */ res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPOST (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_UPLOAD (3)	3.13 KB	2025-07-08 09:41
📄 CURLOPT_POSTFIELDS.3 .\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDS.md .TH CURLOPT_POSTFIELDS 3 "2025-06-27" libcurl .SH NAME CURLOPT_POSTFIELDS \- data to POST to server .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POSTFIELDS, char postdata); .fi .SH DESCRIPTION Pass a char pointer as parameter, pointing to the data buffer to use in an HTTP POST operation or an MQTT subscribe. The data must be formatted and encoded the way you want the server to receive it. libcurl does not convert or encode it in any way. For example, a web server may assume that this data is URL encoded. The data pointed to is NOT copied by the library: as a consequence, it must be preserved by the calling application until the associated transfer finishes. This behavior can be changed (so libcurl does copy the data) by instead using the \fICURLOPT_COPYPOSTFIELDS(3)\fP option. This POST is a normal \fBapplication/x\-www\-form\-urlencoded\fP kind (and libcurl sets that Content\-Type by default when this option is used), which is commonly used by HTML forms. Change Content\-Type with \fICURLOPT_HTTPHEADER(3)\fP. You can use \fIcurl_easy_escape(3)\fP to URL encode your data, if necessary. It returns a pointer to an encoded string that can be passed as \fIpostdata\fP. Using \fICURLOPT_POSTFIELDS(3)\fP implies setting \fICURLOPT_POST(3)\fP to 1. If \fICURLOPT_POSTFIELDS(3)\fP is explicitly set to NULL then libcurl gets the POST data from the read callback. To send a zero\-length (empty) POST, set \fICURLOPT_POSTFIELDS(3)\fP to an empty string, or set \fICURLOPT_POST(3)\fP to 1 and \fICURLOPT_POSTFIELDSIZE(3)\fP to 0. libcurl assumes this option points to a null\-terminated string unless you also set \fICURLOPT_POSTFIELDSIZE(3)\fP to specify the length of the provided data, which then is strictly required if you want to send off null bytes included in the data. Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header, and libcurl adds that header automatically if the POST is either known to be larger than 1MB or if the expected size is unknown. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. To make \fBmultipart/formdata\fP posts, check out the \fICURLOPT_MIMEPOST(3)\fP option combined with \fIcurl_mime_init(3)\fP. Using this option multiple times makes the last set pointer override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http and mqtt .SH EXAMPLE .nf /* send an application/x-www-form-urlencoded POST / int main(void) { CURL curl = curl_easy_init(); if(curl) { const char data = "data to send"; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / size of the POST data if strlen() is not good enough / curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); / pass in a pointer to the data - libcurl does not copy / curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); curl_easy_perform(curl); } / send an application/json POST / curl = curl_easy_init(); if(curl) { const char json = "{\\"name\\": \\"daniel\\"}"; struct curl_slist slist1 = NULL; slist1 = curl_slist_append(slist1, "Content-Type: application/json"); slist1 = curl_slist_append(slist1, "Accept: application/json"); / set custom headers / curl_easy_setopt(curl, CURLOPT_HTTPHEADER, slist1); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / pass in a pointer to the data - libcurl does not copy */ curl_easy_setopt(curl, CURLOPT_POSTFIELDS, json); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COPYPOSTFIELDS (3), .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_POSTFIELDSIZE (3), .BR CURLOPT_READFUNCTION (3), .BR CURLOPT_UPLOAD (3)	3.92 KB	2025-07-08 09:41
📄 CURLOPT_POSTFIELDSIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDSIZE.md .TH CURLOPT_POSTFIELDSIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_POSTFIELDSIZE \- size of POST data pointed to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POSTFIELDSIZE, long size); .fi .SH DESCRIPTION If you want to post static data to the server without having libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this size is set to \-1, libcurl uses strlen() to get the size or relies on the \fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. .SH DEFAULT -1 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf #include <string.h> / for strlen / int main(void) { CURL curl = curl_easy_init(); if(curl) { const char data = "data to send"; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / size of the POST data */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_POSTFIELDSIZE_LARGE (3)	1.51 KB	2025-07-08 09:41
📄 CURLOPT_POSTFIELDSIZE_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_POSTFIELDSIZE_LARGE.md .TH CURLOPT_POSTFIELDSIZE_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POSTFIELDSIZE_LARGE, curl_off_t size); .fi .SH DESCRIPTION If you want to post static data to the server without having libcurl do a strlen() to measure the data size, this option must be used. When this option is used you can post fully binary data, which otherwise is likely to fail. If this size is set to \-1, libcurl uses strlen() to get the size or relies on the \fICURLOPT_READFUNCTION(3)\fP (if used) to signal the end of data. .SH DEFAULT -1 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf extern char large_chunk; /* pointer to somewhere / int main(void) { CURL curl = curl_easy_init(); if(curl) { const char data = large_chunk; curl_off_t length_of_data = 12345; / set somehow / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / size of the POST data */ curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.11.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COPYPOSTFIELDS (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_POSTFIELDSIZE (3)	1.6 KB	2025-07-08 09:41
📄 CURLOPT_POSTQUOTE.3 .\" generated by cd2nroff 0.1 from CURLOPT_POSTQUOTE.md .TH CURLOPT_POSTQUOTE 3 "2025-06-27" libcurl .SH NAME CURLOPT_POSTQUOTE \- (S)FTP commands to run after the transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POSTQUOTE, struct curl_slist cmds); .fi .SH DESCRIPTION Pass a pointer to a linked list of FTP or SFTP commands to pass to the server after your FTP transfer request. The commands are only issued if no error occur. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp and sftp .SH EXAMPLE .nf int main(void) { struct curl_slist cmdlist = NULL; cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); /* pass in the FTP commands to run after the transfer */ curl_easy_setopt(curl, CURLOPT_POSTQUOTE, cmdlist); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } curl_slist_free_all(cmdlist); } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PREQUOTE (3), .BR CURLOPT_QUOTE (3)	1.73 KB	2025-07-08 09:41
📄 CURLOPT_POSTREDIR.3 .\" generated by cd2nroff 0.1 from CURLOPT_POSTREDIR.md .TH CURLOPT_POSTREDIR 3 "2025-06-27" libcurl .SH NAME CURLOPT_POSTREDIR \- how to act on an HTTP POST redirect .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_POSTREDIR, long bitmask); .fi .SH DESCRIPTION Pass a bitmask to control how libcurl acts on redirects after POSTs that get a 301, 302 or 303 response back. A parameter with bit 0 set (value \fBCURL_REDIR_POST_301\fP) tells the library to respect RFC 7231 (section 6.4.2 to 6.4.4) and not convert POST requests into GET requests when following a 301 redirection. Setting bit 1 (value \fBCURL_REDIR_POST_302\fP) makes libcurl maintain the request method after a 302 redirect whilst setting bit 2 (value \fBCURL_REDIR_POST_303\fP) makes libcurl maintain the request method after a 303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that sets all three bits. The non\-RFC behavior is ubiquitous in web browsers, so the library does the conversion by default to maintain consistency. However, a server may require a POST to remain a POST after such a redirection. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* a silly POST example / curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); / example.com is redirected, so we tell libcurl to send POST on 301, 302 and 303 HTTP response codes */ curl_easy_setopt(curl, CURLOPT_POSTREDIR, (long)CURL_REDIR_POST_ALL); curl_easy_perform(curl); } } .fi .SH HISTORY This option was known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0. .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_EFFECTIVE_METHOD (3), .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR CURLOPT_MAXREDIRS (3), .BR CURLOPT_POSTFIELDS (3)	2.26 KB	2025-07-08 09:41
📄 CURLOPT_PREQUOTE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PREQUOTE.md .TH CURLOPT_PREQUOTE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PREQUOTE \- commands to run before an FTP transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PREQUOTE, struct curl_slist cmds); .fi .SH DESCRIPTION Pass a pointer to a linked list of FTP commands to pass to the server after the transfer type is set. The linked list should be a fully valid list of struct curl_slist structs properly filled in as described for \fICURLOPT_QUOTE(3)\fP. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. These commands are not performed when a directory listing is performed, only for file transfers. While \fICURLOPT_QUOTE(3)\fP and \fICURLOPT_POSTQUOTE(3)\fP work for SFTP, this option does not. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf int main(void) { struct curl_slist cmdlist = NULL; cmdlist = curl_slist_append(cmdlist, "SYST"); CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); /* pass in the FTP commands to run */ curl_easy_setopt(curl, CURLOPT_PREQUOTE, cmdlist); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } curl_slist_free_all(cmdlist); } .fi .SH AVAILABILITY Added in curl 7.9.5 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_POSTQUOTE (3), .BR CURLOPT_QUOTE (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_PREREQDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_PREREQDATA.md .TH CURLOPT_PREREQDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_PREREQDATA \- pointer passed to the pre\-request callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PREREQDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the pre\-request callback set with \fICURLOPT_PREREQFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int prereq_callback(void clientp, char conn_primary_ip, char conn_local_ip, int conn_primary_port, int conn_local_port) { printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); return CURL_PREREQFUNC_OK; } int main(void) { struct priv prereq_data; CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.80.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRIMARY_IP (3), .BR CURLINFO_PRIMARY_PORT (3), .BR CURLOPT_PREREQFUNCTION (3)	1.51 KB	2025-07-08 09:41
📄 CURLOPT_PREREQFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_PREREQFUNCTION.md .TH CURLOPT_PREREQFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_PREREQFUNCTION \- user callback called when a connection has been established, but before a request has been made. .SH SYNOPSIS .nf #include <curl/curl.h> /* These are the return codes for the pre-request callback. / #define CURL_PREREQFUNC_OK 0 #define CURL_PREREQFUNC_ABORT 1 / fail the entire transfer / int prereq_callback(void clientp, char conn_primary_ip, char conn_local_ip, int conn_primary_port, int conn_local_port); CURLcode curl_easy_setopt(CURL handle, CURLOPT_PREREQFUNCTION, prereq_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This function gets called by libcurl after a connection has been established or a connection has been reused (including any SSL handshaking), but before any request is actually made on the connection. For example, for HTTP, this callback is called once a connection has been established to the server, but before a GET/HEAD/POST/etc request has been sent. This function may be called multiple times if redirections are enabled and are being followed (see \fICURLOPT_FOLLOWLOCATION(3)\fP). The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or \fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail with result \fICURLE_ABORTED_BY_CALLBACK\fP. This function is passed the following arguments: .IP conn_primary_ip A pointer to a null\-terminated C string containing the primary IP of the remote server established with this connection. For FTP, this is the IP for the control connection. IPv6 addresses are represented without surrounding brackets. .IP conn_local_ip A pointer to a null\-terminated C string containing the originating IP for this connection. IPv6 addresses are represented without surrounding brackets. .IP conn_primary_port The primary port number on the remote server established with this connection. For FTP, this is the port for the control connection. This can be a TCP or a UDP port number depending on the protocol. .IP conn_local_port The originating port number for this connection. This can be a TCP or a UDP port number depending on the protocol. .IP clientp The pointer you set with \fICURLOPT_PREREQDATA(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct priv { void custom; }; static int prereq_callback(void clientp, char conn_primary_ip, char conn_local_ip, int conn_primary_port, int conn_local_port) { printf("Connection made to %s:%d\\n", conn_primary_ip, conn_primary_port); return CURL_PREREQFUNC_OK; } int main(void) { struct priv prereq_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_PREREQFUNCTION, prereq_callback); curl_easy_setopt(curl, CURLOPT_PREREQDATA, &prereq_data); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.80.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRIMARY_IP (3), .BR CURLINFO_PRIMARY_PORT (3), .BR CURLOPT_PREREQDATA (3)	3.39 KB	2025-07-08 09:41
📄 CURLOPT_PRE_PROXY.3 .\" generated by cd2nroff 0.1 from CURLOPT_PRE_PROXY.md .TH CURLOPT_PRE_PROXY 3 "2025-06-27" libcurl .SH NAME CURLOPT_PRE_PROXY \- pre\-proxy host to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PRE_PROXY, char preproxy); .fi .SH DESCRIPTION Set the \fIpreproxy\fP to use for the upcoming request. The parameter should be a char * to a null\-terminated string holding the hostname or dotted numerical IP address. A numerical IPv6 address must be written within [brackets]. To specify port number in this string, append :[port] to the end of the host name. The proxy\(aqs port number may optionally be specified with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using port 1080 for proxies. A pre proxy is a SOCKS proxy that curl connects to before it connects to the HTTP(S) proxy specified in the \fICURLOPT_PROXY(3)\fP option. The pre proxy can only be a SOCKS proxy. The pre proxy string should be prefixed with [scheme]:// to specify which kind of socks is used. Use socks4://, socks4a://, socks5:// or socks5h:// (the last one to enable socks5 and asking the proxy to do the resolving, also known as \fICURLPROXY_SOCKS5_HOSTNAME\fP type) to request the specific SOCKS version to be used. Otherwise SOCKS4 is used as default. Setting the pre proxy string to "" (an empty string) explicitly disables the use of a pre proxy. When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_PRE_PROXY, "socks4://socks-proxy:1080"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_PROXY (3)	2.42 KB	2025-07-08 09:41
📄 CURLOPT_PRIVATE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PRIVATE.md .TH CURLOPT_PRIVATE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PRIVATE \- store a private pointer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PRIVATE, void pointer); .fi .SH DESCRIPTION Pass a void * as parameter, pointing to data that should be associated with this curl handle. The pointer can subsequently be retrieved using \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_PRIVATE(3)\fP option. libcurl itself never does anything with this data. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct private { void custom; }; int main(void) { CURL curl = curl_easy_init(); struct private secrets; if(curl) { struct private extracted; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / store a pointer to our private struct / curl_easy_setopt(curl, CURLOPT_PRIVATE, &secrets); curl_easy_perform(curl); / we can extract the private pointer again too */ curl_easy_getinfo(curl, CURLINFO_PRIVATE, &extracted); } } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRIVATE (3), .BR CURLOPT_STDERR (3), .BR CURLOPT_VERBOSE (3)	1.41 KB	2025-07-08 09:41
📄 CURLOPT_PROGRESSDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROGRESSDATA.md .TH CURLOPT_PROGRESSDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROGRESSDATA \- pointer passed to the progress callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROGRESSDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct progress { char private; size_t size; }; static int progress_callback(void clientp, double dltotal, double dlnow, double ultotal, double ulnow) { struct progress memory = clientp; printf("private: %p\\n", memory->private); / use the values / return 0; / all is good / } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct progress data; /* pass struct to callback */ curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROGRESSFUNCTION (3), .BR CURLOPT_XFERINFOFUNCTION (3)	1.55 KB	2025-07-08 09:41
📄 CURLOPT_PROGRESSFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROGRESSFUNCTION.md .TH CURLOPT_PROGRESSFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROGRESSFUNCTION \- progress meter callback .SH SYNOPSIS .nf #include <curl/curl.h> int progress_callback(void clientp, double dltotal, double dlnow, double ultotal, double ulnow); CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROGRESSFUNCTION, progress_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This option is deprecated and we encourage users to use the newer \fICURLOPT_XFERINFOFUNCTION(3)\fP instead, if you can. This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it is invoked frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. \fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA(3)\fP, it is not used by libcurl but is only passed along from the application to the callback. The callback gets told how much data libcurl is about to transfer and has transferred, in number of bytes. \fIdltotal\fP is the total number of bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl expects to upload in this transfer. \fIulnow\fP is the number of bytes uploaded so far. Unknown/unused argument values passed to the callback are be set to zero (like if you only download data, the upload size remains 0). Many times the callback is called one or more times first, before it knows the data sizes so a program must be made to handle that. Return zero from the callback if everything is fine. If your callback function returns CURL_PROGRESSFUNC_CONTINUE it causes libcurl to continue executing the default progress function. Return 1 from this callback to make libcurl abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. If you transfer data with the multi interface, this function is not called during periods of idleness unless you call the appropriate libcurl function that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. .SH DEFAULT NULL. libcurl has an internal progress meter. That is rarely wanted by users. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct progress { char private; size_t size; }; static int progress_callback(void clientp, double dltotal, double dlnow, double ultotal, double ulnow) { struct progress memory = clientp; printf("private: %p\\n", memory->private); / use the values / return 0; / all is good / } int main(void) { struct progress data; CURL curl = curl_easy_init(); if(curl) { /* pass struct to callback */ curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &data); curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress_callback); curl_easy_perform(curl); } } .fi .SH DEPRECATED Deprecated since 7.32.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NOPROGRESS (3), .BR CURLOPT_VERBOSE (3), .BR CURLOPT_XFERINFOFUNCTION (3)	3.55 KB	2025-07-08 09:41
📄 CURLOPT_PROTOCOLS.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROTOCOLS.md .TH CURLOPT_PROTOCOLS 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROTOCOLS \- allowed protocols .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROTOCOLS, long bitmask); .fi .SH DESCRIPTION This option is deprecated. We strongly recommend using \fICURLOPT_PROTOCOLS_STR(3)\fP instead because this option cannot control all available protocols. Pass a long that holds a bitmask of protocol bits. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have a libcurl built to support a wide range of protocols but still limit specific transfers to only be allowed to use a subset of them. By default libcurl accepts all protocols it supports (\fICURLPROTO_ALL\fP). See also \fICURLOPT_REDIR_PROTOCOLS(3)\fP. These are the available protocol defines: .nf CURLPROTO_DICT CURLPROTO_FILE CURLPROTO_FTP CURLPROTO_FTPS CURLPROTO_GOPHER CURLPROTO_HTTP CURLPROTO_HTTPS CURLPROTO_IMAP CURLPROTO_IMAPS CURLPROTO_LDAP CURLPROTO_LDAPS CURLPROTO_POP3 CURLPROTO_POP3S CURLPROTO_RTMP CURLPROTO_RTMPE CURLPROTO_RTMPS CURLPROTO_RTMPT CURLPROTO_RTMPTE CURLPROTO_RTMPTS CURLPROTO_RTSP CURLPROTO_SCP CURLPROTO_SFTP CURLPROTO_SMB CURLPROTO_SMBS CURLPROTO_SMTP CURLPROTO_SMTPS CURLPROTO_TELNET CURLPROTO_TFTP .fi .SH DEFAULT All protocols built\-in. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(int argc, char argv) { CURL curl = curl_easy_init(); if(curl) { /* pass in the URL from an external source / curl_easy_setopt(curl, CURLOPT_URL, argv[1]); / only allow HTTP, TFTP and SFTP / curl_easy_setopt(curl, CURLOPT_PROTOCOLS, (long)CURLPROTO_HTTP \| CURLPROTO_TFTP \| CURLPROTO_SFTP); / Perform the request */ curl_easy_perform(curl); } } .fi .SH DEPRECATED Deprecated since 7.85.0. .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEFAULT_PROTOCOL (3), .BR CURLOPT_REDIR_PROTOCOLS (3), .BR CURLOPT_URL (3)	2.18 KB	2025-07-08 09:41
📄 CURLOPT_PROTOCOLS_STR.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROTOCOLS_STR.md .TH CURLOPT_PROTOCOLS_STR 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROTOCOLS_STR \- allowed protocols .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROTOCOLS_STR, char spec); .fi .SH DESCRIPTION Pass a pointer to a string that holds a comma\-separated list of case insensitive protocol names (URL schemes) to allow in the transfer. This option allows applications to use libcurl built to support a wide range of protocols but still limit specific transfers to only be allowed to use a subset of them. By default, libcurl accepts all protocols it was built with support for. See also \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. If trying to set a non\-existing protocol or if no matching protocol at all is set, it returns error. These are the available protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS You can set "ALL" as a short\-cut to enable all protocols. Note that by setting all, you may enable protocols that were not supported the day you write this but are introduced in a future libcurl version. \fIcurl_version_info(3)\fP can be used to get a list of all supported protocols in the current libcurl. \fICURLINFO_SCHEME(3)\fP is the recommended way to figure out the protocol used in a previous transfer. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to the internal default. .SH DEFAULT All protocols built\-in .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(int argc, char *argv) { CURL curl = curl_easy_init(); if(curl) { /* pass in the URL from an external source / curl_easy_setopt(curl, CURLOPT_URL, argv[1]); / only allow HTTP, TFTP and SFTP / curl_easy_setopt(curl, CURLOPT_PROTOCOLS_STR, "http,tftp,sftp"); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.85.0 .SH RETURN VALUE Returns CURLE_UNKNOWN_OPTION if the option is not implemented, CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. .SH SEE ALSO .BR CURLINFO_SCHEME (3), .BR CURLOPT_DEFAULT_PROTOCOL (3), .BR CURLOPT_REDIR_PROTOCOLS_STR (3), .BR CURLOPT_URL (3), .BR curl_version_info (3)	2.46 KB	2025-07-08 09:41
📄 CURLOPT_PROXY.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY.md .TH CURLOPT_PROXY 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY \- proxy to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY, char proxy); .fi .SH DESCRIPTION Set the \fIproxy\fP to use for transfers with this easy handle. The parameter should be a char * to a null\-terminated string holding the hostname or dotted numerical IP address. A numerical IPv6 address must be written within [brackets]. To specify port number in this string, append :[port] to the end of the host name. The proxy\(aqs port number may optionally (but discouraged) be specified with the separate option \fICURLOPT_PROXYPORT(3)\fP. If not specified, libcurl defaults to using port 1080 for proxies. The proxy string may be prefixed with [scheme]:// to specify which kind of proxy is used. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The application does not have to keep the string around after setting this option. .IP http:// HTTP Proxy. Default when no scheme or proxy type is specified. .IP https:// HTTPS Proxy. (Added in 7.52.0 for OpenSSL and GnuTLS Since 7.87.0, it also works for BearSSL, mbedTLS, Rustls, Schannel, Secure Transport and wolfSSL.) This uses HTTP/1 by default. Setting \fICURLOPT_PROXYTYPE(3)\fP to \fBCURLPROXY_HTTPS2\fP allows libcurl to negotiate using HTTP/2 with proxy. .IP socks4:// SOCKS4 Proxy. .IP socks4a:// SOCKS4a Proxy. Proxy resolves URL hostname. .IP socks5:// SOCKS5 Proxy. .IP socks5h:// SOCKS5 Proxy. Proxy resolves URL hostname. .PP Without a scheme prefix, \fICURLOPT_PROXYTYPE(3)\fP can be used to specify which kind of proxy the string identifies. When you tell the library to use an HTTP proxy, libcurl transparently converts operations to HTTP even if you specify an FTP URL etc. This may have an impact on what other features of the library you can use, such as \fICURLOPT_QUOTE(3)\fP and similar FTP specifics that do not work unless you tunnel through the HTTP proxy. Such tunneling is activated with \fICURLOPT_HTTPPROXYTUNNEL(3)\fP. Setting the proxy string to "" (an empty string) explicitly disables the use of a proxy, even if there is an environment variable set for it. Unix domain sockets are supported for socks proxies since 7.84.0. Set localhost for the host part. e.g. socks5h://localhost/path/to/socket.sock When you set a hostname to use, do not assume that there is any particular single port number used widely for proxies. Specify it. When a proxy is used, the active FTP mode as set with \fICUROPT_FTPPORT(3)\fP, cannot be used. Doing FTP over an HTTP proxy without \fICURLOPT_HTTPPROXYTUNNEL(3)\fP set makes libcurl do HTTP with an FTP URL over the proxy. For such transfers, common FTP specific options do not work, for example \fICURLOPT_USE_SSL(3)\fP. .SH Authentication The proxy can also be specified with its associated credentials like for ordinary URLs in the style: \fIscheme://username:password@hostname\fP Alternatively, set them using \fICURLOPT_PROXYUSERNAME(3)\fP and \fICURLOPT_PROXYPASSWORD(3)\fP. .SH Environment variables libcurl respects the proxy environment variables named \fBhttp_proxy\fP, \fBftp_proxy\fP, \fBsftp_proxy\fP etc. If set, libcurl uses the specified proxy for that URL scheme. For an "FTP://" URL, the \fBftp_proxy\fP is considered. \fBall_proxy\fP is used if no protocol specific proxy was set. If \fBno_proxy\fP (or \fBNO_PROXY\fP) is set, it is the exact equivalent of setting the \fICURLOPT_NOPROXY(3)\fP option. The \fICURLOPT_PROXY(3)\fP and \fICURLOPT_NOPROXY(3)\fP options override environment variables. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/file.txt"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80"); curl_easy_perform(curl); } } .fi .SH HISTORY Since 7.14.1 the proxy environment variable names can include the protocol scheme. Since 7.21.7 the proxy string supports the socks protocols as "schemes". Since 7.50.2, unsupported schemes in proxy strings cause libcurl to return error. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_PRE_PROXY (3), .BR CURLOPT_PROXYPORT (3), .BR CURLOPT_PROXYTYPE (3)	4.53 KB	2025-07-08 09:41
📄 CURLOPT_PROXYAUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYAUTH.md .TH CURLOPT_PROXYAUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYAUTH \- HTTP proxy authentication methods .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYAUTH, long bitmask); .fi .SH DESCRIPTION Pass a long as parameter, which is set to a bitmask, to tell libcurl which HTTP authentication method(s) you want it to use for your proxy authentication. If more than one bit is set, libcurl first queries the site to see what authentication methods it supports and then it picks the best one you allow it to use. For some methods, this induces an extra network round\-trip. Set the actual name and password with the \fICURLOPT_PROXYUSERPWD(3)\fP option. The bitmask can be constructed by the bits listed and described in the \fICURLOPT_HTTPAUTH(3)\fP man page. .SH DEFAULT CURLAUTH_BASIC .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* use this proxy / curl_easy_setopt(curl, CURLOPT_PROXY, "http://local.example.com:1080"); / allow whatever auth the proxy speaks / curl_easy_setopt(curl, CURLOPT_PROXYAUTH, CURLAUTH_ANY); / set the proxy credentials */ curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "james:007"); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYPORT (3), .BR CURLOPT_PROXYTYPE (3), .BR CURLOPT_PROXYUSERPWD (3)	1.83 KB	2025-07-08 09:41
📄 CURLOPT_PROXYHEADER.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYHEADER.md .TH CURLOPT_PROXYHEADER 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYHEADER \- set of HTTP headers to pass to proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYHEADER, struct curl_slist headers); .fi .SH DESCRIPTION Pass a pointer to a linked list of HTTP headers to pass in your HTTP request sent to a proxy. The rules for this list is identical to the \fICURLOPT_HTTPHEADER(3)\fP option\(aqs. The headers set with this option is only ever used in requests sent to a proxy - when there is also a request sent to a host. The first line in a request (containing the method, usually a GET or POST) is NOT a header and cannot be replaced using this option. Only the lines following the request\-line are headers. Adding this method line in this list of headers causes your request to send an invalid header. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); struct curl_slist list; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy.example.com:80"); list = curl_slist_append(NULL, "Shoesize: 10"); list = curl_slist_append(list, "Accept:"); curl_easy_setopt(curl, CURLOPT_PROXYHEADER, list); curl_easy_perform(curl); curl_slist_free_all(list); /* free the list again */ } } .fi .SH AVAILABILITY Added in curl 7.37.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HEADEROPT (3), .BR CURLOPT_HTTPHEADER (3)	2 KB	2025-07-08 09:41
📄 CURLOPT_PROXYPASSWORD.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYPASSWORD.md .TH CURLOPT_PROXYPASSWORD 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYPASSWORD \- password to use with proxy authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYPASSWORD, char pwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated password to use for authentication with the proxy. The \fICURLOPT_PROXYPASSWORD(3)\fP option should be used in conjunction with the \fICURLOPT_PROXYUSERNAME(3)\fP option. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PASSWORD (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_PROXYUSERNAME (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_PROXYPORT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYPORT.md .TH CURLOPT_PROXYPORT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYPORT \- port number the proxy listens on .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYPORT, long port); .fi .SH DESCRIPTION We discourage use of this option. Pass a long with this option to set the proxy port to connect to unless it is specified in the proxy string \fICURLOPT_PROXY(3)\fP or uses 443 for https proxies and 1080 for all others as default. Disabling this option, setting it to zero, makes it not specified which makes libcurl use the default proxy port number or the port number specified in the proxy URL string. While this accepts a \(aqlong\(aq, the port number is 16 bit so it cannot be larger than 65535. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PROXY, "localhost"); curl_easy_setopt(curl, CURLOPT_PROXYPORT, 8080L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_PRIMARY_PORT (3), .BR CURLOPT_PORT (3), .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYTYPE (3)	1.54 KB	2025-07-08 09:41
📄 CURLOPT_PROXYTYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYTYPE.md .TH CURLOPT_PROXYTYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYTYPE \- proxy protocol type .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYTYPE, long type); .fi .SH DESCRIPTION Pass one of the values below to set the type of the proxy. .IP CURLPROXY_HTTP HTTP Proxy. Default. .IP CURLPROXY_HTTPS HTTPS Proxy using HTTP/1. (Added in 7.52.0 for OpenSSL and GnuTLS. Since 7.87.0, it also works for BearSSL, mbedTLS, Rustls, Schannel, Secure Transport and wolfSSL.) .IP CURLPROXY_HTTPS2 HTTPS Proxy and attempt to speak HTTP/2 over it. (Added in 8.1.0) .IP CURLPROXY_HTTP_1_0 HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for any CONNECT tunneling. It does not change the HTTP version of the actual HTTP requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURLPROXY_SOCKS4 SOCKS4 Proxy. .IP CURLPROXY_SOCKS4A SOCKS4a Proxy. Proxy resolves URL hostname. .IP CURLPROXY_SOCKS5 SOCKS5 Proxy. .IP CURLPROXY_SOCKS5_HOSTNAME SOCKS5 Proxy. Proxy resolves URL hostname. .PP Often it is more convenient to specify the proxy type with the scheme part of the \fICURLOPT_PROXY(3)\fP string. .SH DEFAULT CURLPROXY_HTTP .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "local.example.com:1080"); /* set the proxy type */ curl_easy_setopt(curl, CURLOPT_PROXYTYPE, (long)CURLPROXY_SOCKS5); ret = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYPORT (3)	1.96 KB	2025-07-08 09:41
📄 CURLOPT_PROXYUSERNAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYUSERNAME.md .TH CURLOPT_PROXYUSERNAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYUSERNAME \- username to use for proxy authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYUSERNAME, char username); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated username to use for the transfer. \fICURLOPT_PROXYUSERNAME(3)\fP sets the username to be used in protocol authentication with the proxy. To specify the proxy password use the \fICURLOPT_PROXYPASSWORD(3)\fP. The application does not have to keep the string around after setting this option. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); curl_easy_setopt(curl, CURLOPT_PROXYUSERNAME, "mrsmith"); curl_easy_setopt(curl, CURLOPT_PROXYPASSWORD, "qwerty"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_PROXYPASSWORD (3), .BR CURLOPT_USERNAME (3)	1.56 KB	2025-07-08 09:41
📄 CURLOPT_PROXYUSERPWD.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXYUSERPWD.md .TH CURLOPT_PROXYUSERPWD 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXYUSERPWD \- username and password to use for proxy authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXYUSERPWD, char userpwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be [username]:[password] to use for the connection to the HTTP proxy. Both the name and the password are URL decoded before used, so to include for example a colon in the username you should encode it as %3A. (This is different to how \fICURLOPT_USERPWD(3)\fP is used \- beware.) Use \fICURLOPT_PROXYAUTH(3)\fP to specify the authentication method. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); curl_easy_setopt(curl, CURLOPT_PROXYUSERPWD, "clark%20kent:superman"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYPASSWORD (3), .BR CURLOPT_PROXYTYPE (3), .BR CURLOPT_PROXYUSERNAME (3)	1.72 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_CAINFO.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAINFO.md .TH CURLOPT_PROXY_CAINFO 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_CAINFO \- path to proxy Certificate Authority (CA) bundle .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_CAINFO, char path); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a char pointer to a null\-terminated string naming a file holding one or more certificates to verify the HTTPS proxy with. If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server\(aqs certificate, \fICURLOPT_PROXY_CAINFO(3)\fP need not even indicate an accessible file. This option is by default set to the system path where libcurl\(aqs CA certificate bundle is assumed to be stored, as established at build time. (iOS and macOS only) If curl is built against Secure Transport, then this option is supported for backward compatibility with other SSL engines, but it should not be set. If the option is not set, then curl uses the certificates in the system and user Keychain to verify the peer, which is the preferred method of verifying the peer\(aqs certificate chain. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again and switches back to internal default. The default value for this can be figured out with \fICURLINFO_CAINFO(3)\fP. .SH DEFAULT Built\-in system specific .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / using an HTTPS proxy */ curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO, "/etc/certs/cabundle.pem"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES For TLS backends that do not support certificate files, the \fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to https://curl.se/docs/ssl\-compared.html .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAINFO_BLOB (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_PROXY_CAINFO_BLOB (3), .BR CURLOPT_PROXY_CAPATH (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.75 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_CAINFO_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAINFO_BLOB.md .TH CURLOPT_PROXY_CAINFO_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_CAINFO_BLOB \- proxy Certificate Authority (CA) bundle in PEM format .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_CAINFO_BLOB, struct curl_blob stblob); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a pointer to a curl_blob structure, which contains information (pointer and size) about a memory block with binary data of PEM encoded content holding one or more certificates to verify the HTTPS proxy with. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. If \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the server\(aqs certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed. This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, Secure Transport and rustls .SH EXAMPLE .nf #include <string.h> /* for strlen / extern char strpem; /* strpem must point to a PEM string / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* using an HTTPS proxy */ curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); blob.data = strpem; blob.len = strlen(strpem); blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_PROXY_CAINFO_BLOB, &blob); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.77.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAINFO_BLOB (3), .BR CURLOPT_CAPATH (3), .BR CURLOPT_PROXY_CAINFO (3), .BR CURLOPT_PROXY_CAPATH (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.35 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_CAPATH.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CAPATH.md .TH CURLOPT_PROXY_CAPATH 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_CAPATH \- directory holding HTTPS proxy CA certificates .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_CAPATH, char capath); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a directory holding multiple CA certificates to verify the HTTPS proxy with. If libcurl is built against OpenSSL, the certificate directory must be prepared using the OpenSSL \fBc_rehash\fP utility. This makes sense only when \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled (which it is by default). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again and switch back to internal default. The default value for this can be figured out with \fICURLINFO_CAPATH(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL and mbedTLS .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / using an HTTPS proxy */ curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); curl_easy_setopt(curl, CURLOPT_PROXY_CAPATH, "/etc/cert-dir"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN \- Not supported by the SSL backend CURLE_UNKNOWN_OPTION CURLE_OUT_OF_MEMORY .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_PROXY_CAINFO (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_STDERR (3)	1.93 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_CRLFILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_CRLFILE.md .TH CURLOPT_PROXY_CRLFILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_CRLFILE \- HTTPS proxy Certificate Revocation List file .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_CRLFILE, char file); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a char pointer to a null\-terminated string naming a \fIfile\fP with the concatenation of CRL (in PEM format) to use in the certificate validation that occurs during the SSL exchange. When curl is built to use GnuTLS, there is no way to influence the use of CRL passed to help in the verification process. When libcurl is built with OpenSSL support, X509_V_FLAG_CRL_CHECK and X509_V_FLAG_CRL_CHECK_ALL are both set, requiring CRL check against all the elements of the certificate chain if a CRL file is passed. This option makes sense only when used in combination with the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. A specific error code (\fICURLE_SSL_CRL_BADFILE\fP) is defined with the option. It is returned when the SSL exchange fails because the CRL file cannot be loaded. A failure in certificate verification due to a revocation information found in the CRL does not trigger this specific error. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL and mbedTLS .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:80"); curl_easy_setopt(curl, CURLOPT_PROXY_CRLFILE, "/etc/certs/crl.pem"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.43 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_ISSUERCERT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_ISSUERCERT.md .TH CURLOPT_PROXY_ISSUERCERT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_ISSUERCERT \- proxy issuer SSL certificate filename .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_ISSUERCERT, char file); .fi .SH DESCRIPTION Pass a char pointer to a null\-terminated string naming a \fIfile\fP holding a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer of the HTTPS proxy is indeed the one associated with the certificate provided by the option. This additional check is useful in multi\-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option makes sense only when used in combination with the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to fail). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / using an HTTPS proxy */ curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT, "/etc/certs/cacert.pem"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ISSUERCERT (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.41 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_ISSUERCERT_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_ISSUERCERT_BLOB.md .TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_ISSUERCERT_BLOB, struct curl_blob blob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob struct, which contains information (pointer and size) about a memory block with binary data of a CA certificate in PEM format. If the option is set, an additional check against the peer certificate is performed to verify the issuer of the HTTPS proxy is indeed the one associated with the certificate provided by the option. This additional check is useful in multi\-level PKI where one needs to enforce that the peer certificate is from a specific branch of the tree. This option should be used in combination with the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. Otherwise, the result of the check is not considered as failure. A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, which is returned if the setup of the SSL/TLS session has failed due to a mismatch with the issuer of peer certificate (\fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP has to be set too for the check to fail). If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. This option is an alternative to \fICURLOPT_PROXY_ISSUERCERT(3)\fP which instead expects a filename as input. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf extern char certificateData; / point to the data / size_t filesize; / size of the data / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* using an HTTPS proxy */ curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost:443"); blob.data = certificateData; blob.len = filesize; blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_PROXY_ISSUERCERT_BLOB, &blob); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ISSUERCERT_BLOB (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.77 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_KEYPASSWD.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_KEYPASSWD.md .TH CURLOPT_PROXY_KEYPASSWD 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_KEYPASSWD \- passphrase for the proxy private key .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_KEYPASSWD, char pwd); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a pointer to a null\-terminated string as parameter. It is used as the password required to use the \fICURLOPT_PROXY_SSLKEY(3)\fP private key. You never need a passphrase to load a certificate but you need one to load your private key. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "superman"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_KEYPASSWD (3), .BR CURLOPT_PROXY_SSLKEY (3), .BR CURLOPT_SSH_PRIVATE_KEYFILE (3), .BR CURLOPT_SSLKEY (3)	1.76 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_PINNEDPUBLICKEY.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_PINNEDPUBLICKEY.md .TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_PINNEDPUBLICKEY \- pinned public key for https proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_PINNEDPUBLICKEY, char pinnedpubkey); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string can be the filename of your pinned public key. The file format expected is "PEM" or \&"DER". The string can also be any number of base64 encoded sha256 hashes preceded by "sha256//" and separated by ";" When negotiating a TLS or SSL connection, the https proxy sends a certificate indicating its identity. A public key is extracted from this certificate and if it does not exactly match the public key provided to this option, libcurl aborts the connection before sending or receiving any data. On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); curl_easy_setopt(curl, CURLOPT_PROXY_PINNEDPUBLICKEY, "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjA" "a3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74" "Gxa2eg7fRbEgoChTociMee9wno="); / Perform the request */ curl_easy_perform(curl); } } .fi .SH PUBLIC KEY EXTRACTION If you do not have the https proxy server\(aqs public key file you can extract it from the https proxy server\(aqs certificate. .nf # retrieve the server's certificate if you do not already have it # # be sure to examine the certificate to see if it is what you expected # # Windows-specific: # - Use NUL instead of /dev/null. # - OpenSSL may wait for input instead of disconnecting. Hit enter. # - If you do not have sed, then just copy the certificate into a file: # Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. # openssl s_client -servername www.example.com -connect www.example.com:443 \\ < /dev/null \| sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem # extract public key in pem format from certificate openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem # convert public key from pem to der openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \\ -out www.example.com.pubkey.der # sha256 hash and base64 encode der to string for use openssl dgst -sha256 -binary www.example.com.pubkey.der \| openssl base64 .fi The public key in PEM format contains a header, base64 data and a footer: .nf -----BEGIN PUBLIC KEY----- [BASE 64 DATA] -----END PUBLIC KEY----- .fi .SH HISTORY PEM/DER support: 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL sha256 support: 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL Other SSL backends not supported. .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PINNEDPUBLICKEY (3), .BR CURLOPT_PROXY_CAINFO (3), .BR CURLOPT_PROXY_CAPATH (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3)	3.72 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SERVICE_NAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SERVICE_NAME.md .TH CURLOPT_PROXY_SERVICE_NAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SERVICE_NAME \- proxy authentication service name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SERVICE_NAME, char name); .fi .SH DESCRIPTION Pass a char pointer as parameter to a string holding the \fIname\fP of the service. The default service name is \fB"HTTP"\fP for HTTP based proxies and \fB"rcmd"\fP for SOCKS5. This option allows you to change it. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT See above .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY_SERVICE_NAME, "custom"); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.43.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYTYPE (3), .BR CURLOPT_SERVICE_NAME (3)	1.44 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLCERT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERT.md .TH CURLOPT_PROXY_SSLCERT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLCERT \- HTTPS proxy client certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLCERT, char cert); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a pointer to a null\-terminated string as parameter. The string should be the filename of your client certificate used to connect to the HTTPS proxy. The default format is "P12" on Secure Transport and "PEM" on other engines, and can be changed with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. With Secure Transport, this can also be the nickname of the certificate you wish to authenticate with as it is named in the security database. If you want to use a file from the current directory, please precede it with "./" prefix, in order to avoid confusion with a nickname. When using a client certificate, you most likely also need to provide a private key with \fICURLOPT_PROXY_SSLKEY(3)\fP. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLCERTTYPE (3), .BR CURLOPT_PROXY_SSLKEY (3), .BR CURLOPT_SSLCERT (3)	2.29 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLCERTTYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERTTYPE.md .TH CURLOPT_PROXY_SSLCERTTYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLCERTTYPE \- type of the proxy client SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLCERTTYPE, char type); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the format of your client certificate used when connecting to an HTTPS proxy. Supported formats are "PEM" and "DER", except with Secure Transport or Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or later, or macOS 10.7 or later) and Schannel support "P12" for PKCS#12\-encoded files. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT \&"PEM" .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLCERT (3), .BR CURLOPT_PROXY_SSLKEY (3), .BR CURLOPT_SSLCERTTYPE (3)	2.02 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLCERT_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLCERT_BLOB.md .TH CURLOPT_PROXY_SSLCERT_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLCERT_BLOB \- SSL proxy client certificate from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLCERT_BLOB, struct curl_blob blob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure, which contains information (pointer and size) about a memory block with binary data of the certificate used to connect to the HTTPS proxy. The format must be "P12" on Secure Transport or Schannel. The format must be "P12" or "PEM" on OpenSSL. The string "P12" or \&"PEM" must be specified with \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. This option is an alternative to \fICURLOPT_PROXY_SSLCERT(3)\fP which instead expects a filename as input. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel and Secure Transport .SH EXAMPLE .nf extern char certificateData; / point to data / extern size_t filesize; / size of the data / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; blob.data = certificateData; blob.len = filesize; blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLCERT (3), .BR CURLOPT_PROXY_SSLCERTTYPE (3), .BR CURLOPT_PROXY_SSLKEY (3), .BR CURLOPT_SSLCERT_BLOB (3)	2.27 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLKEY.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEY.md .TH CURLOPT_PROXY_SSLKEY 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLKEY \- private key file for HTTPS proxy client cert .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLKEY, char keyfile); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the filename of your private key used for connecting to the HTTPS proxy. The default format is "PEM" and can be changed with \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. (Windows, iOS and macOS) This option is ignored by Secure Transport and Schannel SSL backends because they expect the private key to be already present in the key chain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLCERT (3), .BR CURLOPT_PROXY_SSLKEYTYPE (3), .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLKEY (3), .BR CURLOPT_SSLKEYTYPE (3)	2.03 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLKEYTYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEYTYPE.md .TH CURLOPT_PROXY_SSLKEYTYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLKEYTYPE \- type of the proxy private key file .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLKEYTYPE, char type); .fi .SH DESCRIPTION This option is for connecting to an HTTPS proxy, not an HTTPS server. Pass a pointer to a null\-terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER", "ENG" and \&"PROV" (the latter added in curl 8.12.0). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEYTYPE, "PEM"); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLCERT (3), .BR CURLOPT_PROXY_SSLKEY (3), .BR CURLOPT_SSLKEYTYPE (3)	1.84 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLKEY_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLKEY_BLOB.md .TH CURLOPT_PROXY_SSLKEY_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLKEY_BLOB \- private key for proxy cert from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLKEY_BLOB, struct curl_blob blob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure that contains information (pointer and size) about the private key for connecting to the HTTPS proxy. Compatible with OpenSSL. The format (like "PEM") must be specified with \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf extern char certificateData; / point to data / extern size_t filesize; / size of data / extern char privateKeyData; /* point to data / extern size_t privateKeySize; / size / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); blob.data = certificateData; blob.len = filesize; blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERT_BLOB, &blob); curl_easy_setopt(curl, CURLOPT_PROXY_SSLCERTTYPE, "PEM"); blob.data = privateKeyData; blob.len = privateKeySize; curl_easy_setopt(curl, CURLOPT_PROXY_SSLKEY_BLOB, &blob); curl_easy_setopt(curl, CURLOPT_PROXY_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLKEY (3), .BR CURLOPT_SSLKEYTYPE (3), .BR CURLOPT_SSLKEY_BLOB (3)	2.17 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSLVERSION.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSLVERSION.md .TH CURLOPT_PROXY_SSLVERSION 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSLVERSION \- preferred HTTPS proxy TLS version .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSLVERSION, long version); .fi .SH DESCRIPTION Pass a long as parameter to control which version of SSL/TLS to attempt to use when connecting to an HTTPS proxy. Use one of the available defines for this purpose. The available options are: .IP CURL_SSLVERSION_DEFAULT The default action. This attempts to figure out the remote SSL protocol version. .IP CURL_SSLVERSION_TLSv1 TLSv1.x .IP CURL_SSLVERSION_TLSv1_0 TLSv1.0 .IP CURL_SSLVERSION_TLSv1_1 TLSv1.1 .IP CURL_SSLVERSION_TLSv1_2 TLSv1.2 .IP CURL_SSLVERSION_TLSv1_3 TLSv1.3 .PP The maximum TLS version can be set by using \fIone\fP of the CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. The MAX macros are not supported for wolfSSL. .IP CURL_SSLVERSION_MAX_DEFAULT The flag defines the maximum supported TLS version as TLSv1.2, or the default value from the SSL library. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_0 The flag defines maximum supported TLS version as TLSv1.0. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_1 The flag defines maximum supported TLS version as TLSv1.1. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_2 The flag defines maximum supported TLS version as TLSv1.2. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_3 The flag defines maximum supported TLS version as TLSv1.3. (Added in 7.54.0) .PP In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were documented to allow \fIonly\fP the specified TLS version, but behavior was inconsistent depending on the TLS library. .SH DEFAULT CURL_SSLVERSION_DEFAULT .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* ask libcurl to use TLS version 1.0 or later / curl_easy_setopt(curl, CURLOPT_SSLVERSION, (long)CURL_SSLVERSION_TLSv1); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_IPRESOLVE (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_USE_SSL (3)	2.7 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSL_CIPHER_LIST.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_CIPHER_LIST.md .TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSL_CIPHER_LIST \- ciphers to use for HTTPS proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSL_CIPHER_LIST, char list); .fi .SH DESCRIPTION Pass a char pointer, pointing to a null\-terminated string holding the list of cipher suites to use for the TLS 1.2 (1.1, 1.0) connection to the HTTPS proxy. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. For setting TLS 1.3 ciphers see \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP. A valid example of a cipher list is: .nf "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" .fi For Schannel, you can use this option to set algorithms but not specific cipher suites. Refer to the ciphers lists document for algorithms. Find more details about cipher lists on this URL: https://curl.se/docs/ssl\-ciphers.html The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL, use internal built\-in list. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://localhost"); curl_easy_setopt(curl, CURLOPT_PROXY_SSL_CIPHER_LIST, "ECDHE-ECDSA-CHACHA20-POLY1305:" "ECDHE-RSA-CHACHA20-POLY1305"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY OpenSSL support added in 7.52.0. wolfSSL, Schannel, Secure Transport, and BearSSL support added in 7.87.0 mbedTLS support added in 8.8.0. Rustls support added in 8.10.0. Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported. .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_PROXY_TLS13_CIPHERS (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_TLS13_CIPHERS (3)	2.66 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSL_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_OPTIONS.md .TH CURLOPT_PROXY_SSL_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSL_OPTIONS \- HTTPS proxy SSL behavior options .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSL_OPTIONS, long bitmask); .fi .SH DESCRIPTION Pass a long with a bitmask to tell libcurl about specific SSL behaviors. Available bits: .IP CURLSSLOPT_ALLOW_BEAST Tells libcurl to not attempt to use any workarounds for a security flaw in the SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, the SSL layer libcurl uses may use a work\-around for this flaw although it might cause interoperability problems with some (older) SSL implementations. WARNING: avoiding this work\-around lessens the security, and by setting this option to 1 you ask for exactly that. This option is only supported for Secure Transport and OpenSSL. .IP CURLSSLOPT_NO_REVOKE Tells libcurl to disable certificate revocation checks for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library), with an exception in the case of Windows\(aq Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) .IP CURLSSLOPT_NO_PARTIALCHAIN Tells libcurl to not accept "partial" certificate chains, which it otherwise does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) .IP CURLSSLOPT_REVOKE_BEST_EFFORT Tells libcurl to ignore certificate revocation checks in case of missing or offline distribution points for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes precedence. (Added in 7.70.0) .IP CURLSSLOPT_NATIVE_CA Tell libcurl to use the operating system\(aqs native CA store for certificate verification. This option is independent of other CA certificate locations set at run time or build time. Those locations are searched in addition to the native CA store. Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), macOS, Android and iOS (added in 8.3.0); with GnuTLS (added in 8.5.0) and with OpenSSL and its forks (LibreSSL, BoringSSL, etc) on Windows (Added in 7.71.0). .IP CURLSSLOPT_AUTO_CLIENT_CERT Tell libcurl to automatically locate and use a client certificate for authentication, when requested by the server. This option is only supported for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the default behavior in libcurl with Schannel. Since the server can request any certificate that supports client authentication in the OS certificate store it could be a privacy violation and unexpected. (Added in 7.77.0) .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); /* weaken TLS only for use with silly proxies */ curl_easy_setopt(curl, CURLOPT_PROXY_SSL_OPTIONS, (long) CURLSSLOPT_ALLOW_BEAST \| CURLSSLOPT_NO_REVOKE); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3)	3.87 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSL_VERIFYHOST.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_VERIFYHOST.md .TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate\(aqs name against host .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSL_VERIFYHOST, long verify); .fi .SH DESCRIPTION Pass a long set to 2L as asking curl to \fIverify\fP in the HTTPS proxy\(aqs certificate name fields against the proxy name. This option determines whether libcurl verifies that the proxy cert contains the correct name for the name it is known as. When \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP is 2, the proxy certificate must indicate that the server is the proxy to which you meant to connect to, or the connection fails. curl considers the proxy the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the hostname in the proxy string which you told curl to use. If \fIverify\fP value is set to 1: In 7.28.0 and earlier: treated as a debug option of some sorts, not supported anymore due to frequently leading to programmer mistakes. From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return an error and leaving the flag untouched. From 7.66.0: treats 1 and 2 the same. When the \fIverify\fP value is 0L, the connection succeeds regardless of the names used in the certificate. Use that ability with caution. See also \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP to verify the digital signature of the proxy certificate. .SH DEFAULT 2 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* Set the default value: strict name check please */ curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYHOST, 2L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_PROXY_CAINFO (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.35 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_SSL_VERIFYPEER.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_SSL_VERIFYPEER.md .TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_SSL_VERIFYPEER \- verify the proxy\(aqs SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_SSL_VERIFYPEER, long verify); .fi .SH DESCRIPTION Pass a long as parameter set to 1L to enable or 0L to disable. This option tells curl to verify the authenticity of the HTTPS proxy\(aqs certificate. A value of 1 means curl verifies; 0 (zero) means it does not. This is the proxy version of \fICURLOPT_SSL_VERIFYPEER(3)\fP that is used for ordinary HTTPS servers. When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can specify alternate certificates with the \fICURLOPT_PROXY_CAINFO(3)\fP option or the \fICURLOPT_PROXY_CAPATH(3)\fP option. When \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to prove that the certificate is authentic, the connection fails. When the option is zero, the peer certificate verification succeeds regardless. Authenticating the certificate is not enough to be sure about the server. You typically also want to ensure that the server is the server you mean to be talking to. Use \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP for that. The check that the hostname in the certificate is valid for the hostname you are connecting to is done independently of the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. WARNING: disabling verification of the certificate allows bad guys to man\-in\-the\-middle the communication without you knowing it. Disabling verification makes the communication insecure. Just having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end\-point. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* Set the default value: strict certificate check please */ curl_easy_setopt(curl, CURLOPT_PROXY_SSL_VERIFYPEER, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	2.94 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_TLS13_CIPHERS.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLS13_CIPHERS.md .TH CURLOPT_PROXY_TLS13_CIPHERS 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_TLS13_CIPHERS \- ciphers suites for proxy TLS 1.3 .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_TLS13_CIPHERS, char list); .fi .SH DESCRIPTION Pass a char pointer, pointing to a null\-terminated string holding the list of cipher suites to use for the TLS 1.3 connection to a proxy. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. For setting TLS 1.2 (1.1, 1.0) ciphers see \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP. A valid example of a cipher list is: .nf "TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256" .fi Find more details about cipher lists on this URL: https://curl.se/docs/ssl\-ciphers.html The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL, use internal built\-in list .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, mbedTLS, rustls and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY_TLS13_CIPHERS, "TLS_CHACHA20_POLY1305_SHA256"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY OpenSSL support added in 7.61.0, available when built with OpenSSL >= 1.1.1. LibreSSL support added in 8.3.0, available when built with LibreSSL >= 3.4.1. wolfSSL support added in 8.10.0. mbedTLS support added in 8.10.0, available when built with mbedTLS >= 3.6.0. Rustls support added in 8.10.0. Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites were set by using the \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP option. .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_TLS13_CIPHERS (3)	2.49 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_TLSAUTH_PASSWORD.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_PASSWORD.md .TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_TLSAUTH_PASSWORD \- password to use for proxy TLS authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_TLSAUTH_PASSWORD, char pwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should point to the null\-terminated password to use for the TLS authentication method specified with the \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP option also be set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_TLSAUTH_TYPE (3), .BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), .BR CURLOPT_TLSAUTH_TYPE (3), .BR CURLOPT_TLSAUTH_USERNAME (3)	1.9 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_TLSAUTH_TYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_TYPE.md .TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_TLSAUTH_TYPE \- HTTPS proxy TLS authentication methods .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_TLSAUTH_TYPE, char type); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the method of the TLS authentication used for the HTTPS connection. Supported method is "SRP". Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to internal default. The application does not have to keep the string around after setting this option. .IP SRP TLS\-SRP authentication. Secure Remote Password authentication for TLS is defined in RFC 5054 and provides mutual authentication if both sides have a shared secret. To use TLS\-SRP, you must also set the \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP options. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), .BR CURLOPT_PROXY_TLSAUTH_USERNAME (3), .BR CURLOPT_TLSAUTH_PASSWORD (3), .BR CURLOPT_TLSAUTH_USERNAME (3)	2.1 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_TLSAUTH_USERNAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TLSAUTH_USERNAME.md .TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_TLSAUTH_USERNAME \- username to use for proxy TLS authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_TLSAUTH_USERNAME, char user); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should point to the null\-terminated username to use for the HTTPS proxy TLS authentication method specified with the \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP option also be set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_PROXY_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.52.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), .BR CURLOPT_PROXY_TLSAUTH_TYPE (3), .BR CURLOPT_TLSAUTH_PASSWORD (3), .BR CURLOPT_TLSAUTH_TYPE (3)	1.91 KB	2025-07-08 09:41
📄 CURLOPT_PROXY_TRANSFER_MODE.3 .\" generated by cd2nroff 0.1 from CURLOPT_PROXY_TRANSFER_MODE.md .TH CURLOPT_PROXY_TRANSFER_MODE 3 "2025-06-27" libcurl .SH NAME CURLOPT_PROXY_TRANSFER_MODE \- append FTP transfer mode to URL for proxy .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PROXY_TRANSFER_MODE, long enabled); .fi .SH DESCRIPTION Pass a long. If the value is set to 1 (one), it tells libcurl to set the transfer mode (binary or ASCII) for FTP transfers done via an HTTP proxy, by appending ;type=a or ;type=i to the URL. Without this setting, or it being set to 0 (zero, the default), \fICURLOPT_TRANSFERTEXT(3)\fP has no effect when doing FTP via a proxy. Beware that not all proxies support this feature. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/old-server/file.txt"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:80"); curl_easy_setopt(curl, CURLOPT_PROXY_TRANSFER_MODE, 1L); curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.18.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CRLF (3), .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_PROXY (3), .BR CURLOPT_TRANSFERTEXT (3)	1.61 KB	2025-07-08 09:41
📄 CURLOPT_PUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_PUT.md .TH CURLOPT_PUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_PUT \- make an HTTP PUT request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_PUT, long put); .fi .SH DESCRIPTION A parameter set to 1 tells the library to use HTTP PUT to transfer data. The data should be set with \fICURLOPT_READDATA(3)\fP and \fICURLOPT_INFILESIZE(3)\fP. This option is \fBdeprecated\fP since version 7.12.1. Use \fICURLOPT_UPLOAD(3)\fP. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf static size_t read_cb(char ptr, size_t size, size_t nmemb, void userdata) { FILE src = userdata; /* copy as much data as possible into the 'ptr' buffer, but no more than 'size' * 'nmemb' bytes / size_t retcode = fread(ptr, size, nmemb, src); return retcode; } int main(void) { CURL curl = curl_easy_init(); if(curl) { FILE src = fopen("local-file", "r"); curl_off_t fsize = 123456; / set this to the size of the input file / / we want to use our own read function / curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); / enable PUT / curl_easy_setopt(curl, CURLOPT_PUT, 1L); / specify target / curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); / now specify which pointer to pass to our callback / curl_easy_setopt(curl, CURLOPT_READDATA, src); / Set the size of the file to upload / curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); / Now run off and do what you have been told */ curl_easy_perform(curl); } } .fi .SH DEPRECATED Deprecated since 7.12.1. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPGET (3), .BR CURLOPT_MIMEPOST (3), .BR CURLOPT_POSTFIELDS (3), .BR CURLOPT_UPLOAD (3)	2 KB	2025-07-08 09:41
📄 CURLOPT_QUICK_EXIT.3 .\" generated by cd2nroff 0.1 from CURLOPT_QUICK_EXIT.md .TH CURLOPT_QUICK_EXIT 3 "2025-06-27" libcurl .SH NAME CURLOPT_QUICK_EXIT \- allow to exit quickly .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_QUICK_EXIT, long value); .fi .SH DESCRIPTION Pass a long as a parameter, 1L meaning that when recovering from a timeout, libcurl should skip lengthy cleanups that are intended to avoid all kinds of leaks (threads etc.), as the caller program is about to call exit() anyway. This allows for a swift termination after a DNS timeout for example, by canceling and/or forgetting about a resolver thread, at the expense of a possible (though short\-lived) leak of associated resources. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_QUICK_EXIT, 1L); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.87.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_FAILONERROR (3), .BR CURLOPT_RESOLVE (3)	1.29 KB	2025-07-08 09:41
📄 CURLOPT_QUOTE.3 .\" generated by cd2nroff 0.1 from CURLOPT_QUOTE.md .TH CURLOPT_QUOTE 3 "2025-06-27" libcurl .SH NAME CURLOPT_QUOTE \- (S)FTP commands to run before transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_QUOTE, struct curl_slist cmds); .fi .SH DESCRIPTION Pass a pointer to a linked list of FTP or SFTP commands to pass to the server prior to your request. This is done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of \(aqstruct curl_slist\(aq structs properly filled in with text strings. Use \fIcurl_slist_append(3)\fP to append strings (commands) to the list, and clear the entire list afterwards with \fIcurl_slist_free_all(3)\fP. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. When speaking to an FTP server, prefix the command with an asterisk () to make libcurl continue even if the command fails as by default libcurl stops at first failure. The set of valid FTP commands depends on the server (see RFC 959 for a list of mandatory commands). libcurl does not inspect, parse or "understand" the commands passed to the server using this option. If you change connection state, working directory or similar using quote commands, libcurl does not know about it. The path arguments for FTP or SFTP can use single or double quotes to distinguish a space from being the parameter separator or being a part of the path. e.g. rename with sftp using a quote command like this: .nf "rename 'test/_upload.txt' 'test/Hello World.txt'" .fi .SH SFTP commands .IP "atime date file" The atime command sets the last access time of the file named by the file operand. The date expression can be all sorts of date strings, see the \fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) .IP "chgrp group file" The chgrp command sets the group ID of the file named by the file operand to the group ID specified by the group operand. The group operand is a decimal integer group ID. .IP "chmod mode file" The chmod command modifies the file mode bits of the specified file. The mode operand is an octal integer mode number. .IP "chown user file" The chown command sets the owner of the file named by the file operand to the user ID specified by the user operand. The user operand is a decimal integer user ID. .IP "ln source_file target_file" The \fBln\fP and \fBsymlink\fP commands create a symbolic link at the target_file location pointing to the source_file location. .IP "mkdir directory_name" The mkdir command creates the directory named by the directory_name operand. .IP "mtime date file" The mtime command sets the last modification time of the file named by the file operand. The date expression can be all sorts of date strings, see the \fIcurl_getdate(3)\fP man page for date expression details. (Added in 7.73.0) .IP pwd The \fBpwd\fP command returns the absolute path of the current working directory. .IP "rename source target" The rename command renames the file or directory named by the source operand to the destination path named by the target operand. .IP "rm file" The rm command removes the file specified by the file operand. .IP "rmdir directory" The rmdir command removes the directory entry specified by the directory operand, provided it is empty. .IP "statvfs file" The statvfs command returns statistics on the file system in which specified file resides. (Added in 7.49.0) .IP "symlink source_file target_file" See ln. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp and sftp .SH EXAMPLE .nf int main(void) { struct curl_slist cmdlist = NULL; cmdlist = curl_slist_append(cmdlist, "RNFR source-name"); cmdlist = curl_slist_append(cmdlist, "RNTO new-name"); CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/foo.bin"); / pass in the FTP commands to run before the transfer / curl_easy_setopt(curl, CURLOPT_QUOTE, cmdlist); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } curl_slist_free_all(cmdlist); } .fi .SH HISTORY SFTP support added in 7.16.3. \-prefix for SFTP added in 7.24.0 .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_DIRLISTONLY (3), .BR CURLOPT_POSTQUOTE (3), .BR CURLOPT_PREQUOTE (3)	4.63 KB	2025-07-08 09:41
📄 CURLOPT_RANDOM_FILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_RANDOM_FILE.md .TH CURLOPT_RANDOM_FILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_RANDOM_FILE \- file to read random data from .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RANDOM_FILE, char path); .fi .SH DESCRIPTION Deprecated option. It serves no purpose anymore. .SH DEFAULT NULL, not used .SH DEPRECATED Deprecated since 7.84.0. .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_EGDSOCKET (3)	687 B	2025-07-08 09:41
📄 CURLOPT_RANGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_RANGE.md .TH CURLOPT_RANGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_RANGE \- byte range to request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RANGE, char range); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should contain the specified range you want to retrieve. It should be in the format "X\-Y", where either X or Y may be left out and X and Y are byte indexes. HTTP transfers also support several intervals, separated with commas as in \fI"X\-Y,N\-M"\fP. Using this kind of multiple intervals causes the HTTP server to send the response document in pieces (using standard MIME separation techniques) as a multiple part response which libcurl returns as\-is. It contains meta information in addition to the requested bytes. Parsing or otherwise transforming this response is the responsibility of the caller. Unfortunately, the HTTP standard (RFC 7233 section 3.1) allows servers to ignore range requests so even when you set \fICURLOPT_RANGE(3)\fP for a request, you may end up getting the full response sent back. For RTSP, the formatting of a range should follow RFC 2326 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in \fBnpt\fP, \fButc\fP, or \fBsmpte\fP formats. For HTTP PUT uploads this option should not be used, since it may conflict with other options. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects file, ftp, http, rtsp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / get the first 200 bytes / curl_easy_setopt(curl, CURLOPT_RANGE, "0-199"); / Perform the request */ curl_easy_perform(curl); } } .fi .SH HISTORY FILE since 7.18.0, RTSP since 7.20.0 .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAXFILESIZE_LARGE (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_RESUME_FROM (3)	2.39 KB	2025-07-08 09:41
📄 CURLOPT_READDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_READDATA.md .TH CURLOPT_READDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_READDATA \- pointer passed to the read callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_READDATA, void pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the file read function. If you use the \fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you get as input in the fourth argument to the callback. If you do not specify a read callback but instead rely on the default internal read function, this data must be a valid readable FILE * (cast to \(aqvoid \(aq). If you are using libcurl as a DLL on Windows, you must use the \fICURLOPT_READFUNCTION(3)\fP callback if you set this option, otherwise you might experience crashes. .SH DEFAULT stdin .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct MyData { void custom; }; int main(void) { CURL curl = curl_easy_init(); struct MyData this; if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / pass pointer that gets passed in to the CURLOPT_READFUNCTION callback */ curl_easy_setopt(curl, CURLOPT_READDATA, &this); curl_easy_perform(curl); } } .fi .SH HISTORY This option was once known by the older name CURLOPT_INFILE, the name \fICURLOPT_READDATA(3)\fP was introduced in 7.9.7. .SH AVAILABILITY Added in curl 7.9.7 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HEADERDATA (3), .BR CURLOPT_READFUNCTION (3), .BR CURLOPT_WRITEDATA (3), .BR CURLOPT_WRITEFUNCTION (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_READFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_READFUNCTION.md .TH CURLOPT_READFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_READFUNCTION \- read callback for data uploads .SH SYNOPSIS .nf #include <curl/curl.h> size_t read_callback(char buffer, size_t size, size_t nitems, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_READFUNCTION, read_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, as the prototype shows above. This callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer \- like if you ask it to upload or post data to the server. The data area pointed at by the pointer \fIbuffer\fP should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes by your function. \fIsize\fP is always 1. Set the \fIuserdata\fP argument with the \fICURLOPT_READDATA(3)\fP option. Your function must return the actual number of bytes that it stored in the data area pointed at by the pointer \fIbuffer\fP. Returning 0 signals end\-of\-file to the library and causes it to stop the current transfer. If you stop the current transfer by returning 0 "pre\-maturely" (i.e before the server expected it, like when you have said you would upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that is not sent. The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer. The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this connection to pause. See \fIcurl_easy_pause(3)\fP for further details. \fBBugs\fP: when doing TFTP uploads, you must return the exact amount of data that the callback wants, or it is considered the final packet by the server end and the transfer ends there. If you set this callback pointer to NULL, or do not set it at all, the default internal read function is used. It is doing an fread() on the FILE userdata set with \fICURLOPT_READDATA(3)\fP. You can set the total size of the data you are sending by using \fICURLOPT_INFILESIZE_LARGE(3)\fP or \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP, depending on the type of transfer. For some transfer types it may be required and it allows for better error checking. When this option is used in combination with telling libcurl to follow redirects with \fICURLOPT_FOLLOWLOCATION(3)\fP, the data might need to be rewound and sent again. The \fICURLOPT_SEEKFUNCTION(3)\fP can then be invoked for that rewind operation. .SH DEFAULT fread(3) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf size_t read_callback(char ptr, size_t size, size_t nmemb, void userdata) { FILE readhere = (FILE )userdata; curl_off_t nread; /* copy as much data as possible into the 'ptr' buffer, but no more than 'size' * 'nmemb' bytes. / size_t retcode = fread(ptr, size, nmemb, readhere); nread = (curl_off_t)retcode; fprintf(stderr, " We read %" CURL_FORMAT_CURL_OFF_T " bytes from file\\n", nread); return retcode; } int main(int argc, char argv) { FILE file = fopen(argv[1], "rb"); CURLcode result; CURL curl = curl_easy_init(); if(curl) { /* set callback to use / curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); / pass in suitable argument to callback / curl_easy_setopt(curl, CURLOPT_READDATA, (void )file); result = curl_easy_perform(curl); } } .fi .SH HISTORY CURL_READFUNC_PAUSE return code was added in 7.18.0 and CURL_READFUNC_ABORT was added in 7.12.1. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_POST (3), .BR CURLOPT_READDATA (3), .BR CURLOPT_SEEKFUNCTION (3), .BR CURLOPT_UPLOAD (3), .BR CURLOPT_UPLOAD_BUFFERSIZE (3), .BR CURLOPT_WRITEFUNCTION (3)	3.82 KB	2025-07-08 09:41
📄 CURLOPT_REDIR_PROTOCOLS.3 .\" generated by cd2nroff 0.1 from CURLOPT_REDIR_PROTOCOLS.md .TH CURLOPT_REDIR_PROTOCOLS 3 "2025-06-27" libcurl .SH NAME CURLOPT_REDIR_PROTOCOLS \- protocols allowed to redirect to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_REDIR_PROTOCOLS, long bitmask); .fi .SH DESCRIPTION This option is deprecated. We strongly recommend using \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP instead because this option cannot control all available protocols. Pass a long that holds a bitmask of protocol bits. If used, this bitmask limits what protocols libcurl may use in a transfer that it follows to in a redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to limit specific transfers to only be allowed to use a subset of protocols in redirections. Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this option. By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). \fICURLPROTO_ALL\fP enables all protocols on redirect, including those otherwise disabled for security. These are the available protocol defines: .nf CURLPROTO_DICT CURLPROTO_FILE CURLPROTO_FTP CURLPROTO_FTPS CURLPROTO_GOPHER CURLPROTO_HTTP CURLPROTO_HTTPS CURLPROTO_IMAP CURLPROTO_IMAPS CURLPROTO_LDAP CURLPROTO_LDAPS CURLPROTO_POP3 CURLPROTO_POP3S CURLPROTO_RTMP CURLPROTO_RTMPE CURLPROTO_RTMPS CURLPROTO_RTMPT CURLPROTO_RTMPTE CURLPROTO_RTMPTS CURLPROTO_RTSP CURLPROTO_SCP CURLPROTO_SFTP CURLPROTO_SMB CURLPROTO_SMBS CURLPROTO_SMTP CURLPROTO_SMTPS CURLPROTO_TELNET CURLPROTO_TFTP .fi .SH DEFAULT HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 SMB and SMBS. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(int argc, char argv) { CURL curl = curl_easy_init(); if(curl) { /* pass in the URL from an external source / curl_easy_setopt(curl, CURLOPT_URL, argv[1]); / only allow redirects to HTTP and HTTPS URLs / curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, (long) CURLPROTO_HTTP \| CURLPROTO_HTTPS); / Perform the request */ curl_easy_perform(curl); } } .fi .SH DEPRECATED Deprecated since 7.85.0. .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_SCHEME (3), .BR CURLOPT_DEFAULT_PROTOCOL (3), .BR CURLOPT_PROTOCOLS (3), .BR CURLOPT_REDIR_PROTOCOLS_STR (3)	2.53 KB	2025-07-08 09:41
📄 CURLOPT_REDIR_PROTOCOLS_STR.3 .\" generated by cd2nroff 0.1 from CURLOPT_REDIR_PROTOCOLS_STR.md .TH CURLOPT_REDIR_PROTOCOLS_STR 3 "2025-06-27" libcurl .SH NAME CURLOPT_REDIR_PROTOCOLS_STR \- protocols allowed to redirect to .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_REDIR_PROTOCOLS_STR, char spec); .fi .SH DESCRIPTION Pass a pointer to a string that holds a comma\-separated list of case insensitive protocol names (URL schemes). That list limits what protocols libcurl may use in a transfer that it follows to in a redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This option allows applications to limit specific transfers to only be allowed to use a subset of protocols in redirections. Protocols denied by \fICURLOPT_PROTOCOLS_STR(3)\fP are not overridden by this option. By default libcurl allows HTTP, HTTPS, FTP and FTPS on redirects (since 7.65.2). These are the available protocols: DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, POP3, POP3S, RTMP, RTMPE, RTMPS, RTMPT, RTMPTE, RTMPTS, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS, WSS You can set "ALL" as a short\-cut to enable all protocols. Note that by setting all, you may enable protocols that were not supported the day you write this but are introduced in a future libcurl version. If trying to set a non\-existing protocol or if no matching protocol at all is set, it returns error. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to internal default. The application does not have to keep the string around after setting this option. .SH DEFAULT HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). Older versions defaulted to all protocols except FILE, SCP and since 7.40.0 SMB and SMBS. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(int argc, char *argv) { CURL curl = curl_easy_init(); if(curl) { /* pass in the URL from an external source / curl_easy_setopt(curl, CURLOPT_URL, argv[1]); / only allow redirects to HTTP and HTTPS URLs / curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS_STR, "http,https"); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.85.0 .SH RETURN VALUE Returns CURLE_UNKNOWN_OPTION if the option is not implemented, CURLE_UNSUPPORTED_PROTOCOL if a listed protocol is not supported or disabled, CURLE_BAD_FUNCTION_ARGUMENT if no protocol is listed else CURLE_OK. .SH SEE ALSO .BR CURLINFO_SCHEME (3), .BR CURLOPT_DEFAULT_PROTOCOL (3), .BR CURLOPT_PROTOCOLS (3), .BR CURLOPT_PROTOCOLS_STR (3), .BR CURLOPT_REDIR_PROTOCOLS (3)	2.64 KB	2025-07-08 09:41
📄 CURLOPT_REFERER.3 .\" generated by cd2nroff 0.1 from CURLOPT_REFERER.md .TH CURLOPT_REFERER 3 "2025-06-27" libcurl .SH NAME CURLOPT_REFERER \- the HTTP referer header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_REFERER, char where); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It is used to set the Referer: header field in the HTTP request sent to the remote server. You can set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / tell it where we found the link to this place */ curl_easy_setopt(curl, CURLOPT_REFERER, "https://example.org/me.html"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_URL (3), .BR CURLINFO_REFERER (3), .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_USERAGENT (3)	1.41 KB	2025-07-08 09:41
📄 CURLOPT_REQUEST_TARGET.3 .\" generated by cd2nroff 0.1 from CURLOPT_REQUEST_TARGET.md .TH CURLOPT_REQUEST_TARGET 3 "2025-06-27" libcurl .SH NAME CURLOPT_REQUEST_TARGET \- alternative target for this request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_REQUEST_TARGET, string); .fi .SH DESCRIPTION Pass a char pointer to string which libcurl uses in the upcoming request instead of the path as extracted from the URL. libcurl passes on the verbatim string in its request without any filter or other safe guards. That includes white space and control characters. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "OPTIONS"); / issue an OPTIONS * request (no leading slash) / curl_easy_setopt(curl, CURLOPT_REQUEST_TARGET, ""); /* Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_HTTPGET (3), .BR CURLOPT_PATH_AS_IS (3), .BR CURLOPT_URL (3)	1.57 KB	2025-07-08 09:41
📄 CURLOPT_RESOLVE.3 .\" generated by cd2nroff 0.1 from CURLOPT_RESOLVE.md .TH CURLOPT_RESOLVE 3 "2025-06-27" libcurl .SH NAME CURLOPT_RESOLVE \- provide custom hostname to IP address resolves .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RESOLVE, struct curl_slist hosts); .fi .SH DESCRIPTION Pass a pointer to a linked list of strings with hostname resolve information to use for requests with this handle. The linked list should be a fully valid list of \fBstruct curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. Each resolve rule to add should be written using the format .nf [+]HOST:PORT:ADDRESS[,ADDRESS] .fi HOST is the name libcurl wants to resolve, PORT is the port number of the service where libcurl wants to connect to the HOST and ADDRESS is one or more numerical IP addresses. If you specify multiple IP addresses they need to be separated by comma. If libcurl is built to support IPv6, each of the ADDRESS entries can of course be either IPv4 or IPv6 style addressing. Specify the host as a single asterisk (\fI\fP) to match all names. This wildcard is resolved last so any resolve with a specific host and port number is given priority. This option effectively populates the DNS cache with entries for the host+port pair so redirects and everything that operations against the HOST+PORT instead use your provided ADDRESS. The optional leading plus (\fI+\fP) specifies that the new entry should timeout. Entries added without the leading plus character never times out whereas entries added with \fI+HOST:...\fP times out just like ordinary DNS cache entries. If the DNS cache already has an entry for the given host+port pair, the new entry overrides the former one. An ADDRESS provided by this option is only used if not restricted by the setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version. To remove names from the DNS cache again, to stop providing these fake resolves, include a string in the linked list that uses the format .nf -HOST:PORT .fi The entry to remove must be prefixed with a dash, and the hostname and port number must exactly match what was added previously. Provide IPv6 addresses within [brackets]. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl; struct curl_slist host = NULL; host = curl_slist_append(NULL, "example.com:443:127.0.0.1"); host = curl_slist_append(host, "example.com:443:[2001:db8::252f:efd6]"); curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_RESOLVE, host); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); / always cleanup */ curl_easy_cleanup(curl); } curl_slist_free_all(host); } .fi .SH HISTORY Added in 7.21.3. Removal support added in 7.42.0. Support for providing the ADDRESS within [brackets] was added in 7.57.0. Support for providing multiple IP addresses per entry was added in 7.59.0. Support for adding non\-permanent entries by using the "+" prefix was added in 7.75.0. Support for specifying the host component as an IPv6 address was added in 8.13.0. .SH AVAILABILITY Added in curl 7.21.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECT_TO (3), .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_IPRESOLVE (3)	3.75 KB	2025-07-08 09:41
📄 CURLOPT_RESOLVER_START_DATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_RESOLVER_START_DATA.md .TH CURLOPT_RESOLVER_START_DATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_RESOLVER_START_DATA \- pointer passed to the resolver start callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RESOLVER_START_DATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP is be untouched by libcurl and passed as the third argument in the resolver start callback set with \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static int resolver_start_cb(void resolver_state, void reserved, void userdata) { (void)reserved; printf("Received resolver_state=%p userdata=%p\\n", resolver_state, userdata); return 0; } int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb); curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.59.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PREREQFUNCTION (3), .BR CURLOPT_RESOLVER_START_FUNCTION (3)	1.5 KB	2025-07-08 09:41
📄 CURLOPT_RESOLVER_START_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_RESOLVER_START_FUNCTION.md .TH CURLOPT_RESOLVER_START_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_RESOLVER_START_FUNCTION \- callback called before a new name resolve is started .SH SYNOPSIS .nf #include <curl/curl.h> int resolver_start_cb(void resolver_state, void reserved, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_RESOLVER_START_FUNCTION, resolver_start_cb); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl every time before a new resolve request is started. \fIresolver_state\fP points to a backend\-specific resolver state. Currently only the ares resolver backend has a resolver state. It can be used to set up any desired option on the ares channel before it is used, for example setting up socket callback options. \fIreserved\fP is reserved. \fIuserdata\fP is the user pointer set with the \fICURLOPT_RESOLVER_START_DATA(3)\fP option. The callback must return 0 on success. Returning a non\-zero value causes the resolve to fail. .SH DEFAULT NULL (No callback) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static int start_cb(void resolver_state, void reserved, void userdata) { (void)reserved; printf("Received resolver_state=%p userdata=%p\\n", resolver_state, userdata); return 0; } int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_RESOLVER_START_FUNCTION, start_cb); curl_easy_setopt(curl, CURLOPT_RESOLVER_START_DATA, curl); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.59.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PREREQFUNCTION (3), .BR CURLOPT_RESOLVER_START_DATA (3)	2.1 KB	2025-07-08 09:41
📄 CURLOPT_RESUME_FROM.3 .\" generated by cd2nroff 0.1 from CURLOPT_RESUME_FROM.md .TH CURLOPT_RESUME_FROM 3 "2025-06-27" libcurl .SH NAME CURLOPT_RESUME_FROM \- offset to resume transfer from .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RESUME_FROM, long from); .fi .SH DESCRIPTION Pass a long as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). For FTP, set this option to \-1 to make the transfer start from the end of the target file (useful to continue an interrupted upload). When doing uploads with FTP, the resume position is where in the local/source file libcurl should try to resume the upload from and it then appends the source file to the remote target file. If you need to resume a transfer beyond the 2GB limit, use \fICURLOPT_RESUME_FROM_LARGE(3)\fP instead. .SH DEFAULT 0, not used .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { long size_of_file = 6789; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); /* resume upload at byte index 200 / curl_easy_setopt(curl, CURLOPT_RESUME_FROM, 200L); / ask for upload / curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); / set total data amount to expect / curl_easy_setopt(curl, CURLOPT_INFILESIZE, size_of_file); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INFILESIZE (3), .BR CURLOPT_RANGE (3), .BR CURLOPT_RESUME_FROM_LARGE (3)	1.83 KB	2025-07-08 09:41
📄 CURLOPT_RESUME_FROM_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_RESUME_FROM_LARGE.md .TH CURLOPT_RESUME_FROM_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_RESUME_FROM_LARGE \- offset to resume transfer from .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RESUME_FROM_LARGE, curl_off_t from); .fi .SH DESCRIPTION Pass a curl_off_t as parameter. It contains the offset in number of bytes that you want the transfer to start from. Set this option to 0 to make the transfer start from the beginning (effectively disabling resume). For FTP, set this option to \-1 to make the transfer start from the end of the target file (useful to continue an interrupted upload). When doing uploads with FTP, the resume position is where in the local/source file libcurl should try to resume the upload from and it appends the source file to the remote target file. .SH DEFAULT 0, not used .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_off_t resume_position = 1234; /* get it somehow / curl_off_t file_size = 9876; / get it somehow as well / curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com"); / resuming upload at this position, possibly beyond 2GB / curl_easy_setopt(curl, CURLOPT_RESUME_FROM_LARGE, resume_position); / ask for upload / curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); / set total data amount to expect / curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, file_size); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.11.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INFILESIZE_LARGE (3), .BR CURLOPT_RANGE (3), .BR CURLOPT_RESUME_FROM (3)	1.92 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_CLIENT_CSEQ.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_CLIENT_CSEQ.md .TH CURLOPT_RTSP_CLIENT_CSEQ 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_CLIENT_CSEQ \- RTSP client CSEQ number .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_CLIENT_CSEQ, long cseq); .fi .SH DESCRIPTION Pass a long to set the CSEQ number to issue for the next RTSP request. Useful if the application is resuming a previously broken connection. The CSEQ increments from this new number henceforth. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); curl_easy_setopt(curl, CURLOPT_RTSP_CLIENT_CSEQ, 1234L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_CLIENT_CSEQ (3), .BR CURLINFO_RTSP_SERVER_CSEQ (3), .BR CURLOPT_RTSP_REQUEST (3), .BR CURLOPT_RTSP_SERVER_CSEQ (3)	1.22 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_REQUEST.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_REQUEST.md .TH CURLOPT_RTSP_REQUEST 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_REQUEST \- RTSP request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_REQUEST, long request); .fi .SH DESCRIPTION Tell libcurl what kind of RTSP request to make. Pass one of the following RTSP enum values as a long in the \fIrequest\fP argument. Unless noted otherwise, commands require the Session ID to be initialized. .IP CURL_RTSPREQ_OPTIONS Used to retrieve the available methods of the server. The application is responsible for parsing and obeying the response. The session ID is not needed for this method. .IP CURL_RTSPREQ_DESCRIBE Used to get the low level description of a stream. The application should note what formats it understands in the \fI\(aqAccept:\(aq\fP header. Unless set manually, libcurl automatically adds in \fI\(aqAccept: application/sdp\(aq\fP. Time\-condition headers are added to Describe requests if the \fICURLOPT_TIMECONDITION(3)\fP option is used. (The session ID is not needed for this method) .IP CURL_RTSPREQ_ANNOUNCE When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can use Announce to inform the server of all the meta\-information about the session. ANNOUNCE acts like an HTTP PUT or POST just like \fICURL_RTSPREQ_SET_PARAMETER\fP .IP CURL_RTSPREQ_SETUP Setup is used to initialize the transport layer for the session. The application must set the desired Transport options for a session by using the \fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl extracts and uses the session ID in the response to this request. The session ID is not needed for this method. .IP CURL_RTSPREQ_PLAY Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to modify the playback time (e.g. \fInpt=10\-15\fP). .IP CURL_RTSPREQ_PAUSE Send a Pause command to the server. Use the \fICURLOPT_RANGE(3)\fP option with a single value to indicate when the stream should be halted. (e.g. \fInpt=25\fP) .IP CURL_RTSPREQ_TEARDOWN This command terminates an RTSP session. Simply closing a connection does not terminate the RTSP session since it is valid to control an RTSP session over different connections. .IP CURL_RTSPREQ_GET_PARAMETER Retrieve a parameter from the server. By default, libcurl adds a \fIContent\-Type: text/parameters\fP header on all non\-empty requests unless a custom one is set. GET_PARAMETER acts just like an HTTP PUT or POST (see \fICURL_RTSPREQ_SET_PARAMETER\fP). Applications wishing to send a heartbeat message (e.g. in the presence of a server\-specified timeout) should send use an empty GET_PARAMETER request. .IP CURL_RTSPREQ_SET_PARAMETER Set a parameter on the server. By default, libcurl uses a Content\-Type: text/parameters* header unless a custom one is set. The interaction with SET_PARAMETER is much like an HTTP PUT or POST. An application may either use \fICURLOPT_UPLOAD(3)\fP with \fICURLOPT_READDATA(3)\fP like an HTTP PUT, or it may use \fICURLOPT_POSTFIELDS(3)\fP like an HTTP POST. No chunked transfers are allowed, so the application must set the \fICURLOPT_INFILESIZE(3)\fP in the former and \fICURLOPT_POSTFIELDSIZE(3)\fP in the latter. Also, there is no use of multi\-part POSTs within RTSP. .IP CURL_RTSPREQ_RECORD Used to tell the server to record a session. Use the \fICURLOPT_RANGE(3)\fP option to modify the record time. .IP CURL_RTSPREQ_RECEIVE This is a special request because it does not send any data to the server. The application may call this function in order to receive interleaved RTP data. It returns after processing one read buffer of data in order to give the application a chance to run. .SH DEFAULT .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); / ask for options */ curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_OPTIONS); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_RTSP_SESSION_ID (3), .BR CURLOPT_RTSP_STREAM_URI (3)	4.47 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_SERVER_CSEQ.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_SERVER_CSEQ.md .TH CURLOPT_RTSP_SERVER_CSEQ 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_SERVER_CSEQ \- RTSP server CSEQ number .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_SERVER_CSEQ, long cseq); .fi .SH DESCRIPTION Pass a long to set the CSEQ number to expect for the next RTSP Server to Client request. \fBNOTE\fP: this feature (listening for Server requests) is unimplemented. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); curl_easy_setopt(curl, CURLOPT_RTSP_SERVER_CSEQ, 1234L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_RTSP_SERVER_CSEQ (3), .BR CURLOPT_RTSP_CLIENT_CSEQ (3), .BR CURLOPT_RTSP_STREAM_URI (3)	1.16 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_SESSION_ID.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_SESSION_ID.md .TH CURLOPT_RTSP_SESSION_ID 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_SESSION_ID \- RTSP session ID .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_SESSION_ID, char id); .fi .SH DESCRIPTION Pass a char pointer as a parameter to set the value of the current RTSP Session ID for the handle. Useful for resuming an in\-progress session. Once this value is set to any non\-NULL value, libcurl returns \fICURLE_RTSP_SESSION_ERROR\fP if ID received from the server does not match. If unset (or set to NULL), libcurl automatically sets the ID the first time the server sets it in a response. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; char prev_id = "old"; /* saved from before somehow */ curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); curl_easy_setopt(curl, CURLOPT_RTSP_SESSION_ID, prev_id); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_RTSP_REQUEST (3), .BR CURLOPT_RTSP_STREAM_URI (3)	1.6 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_STREAM_URI.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_STREAM_URI.md .TH CURLOPT_RTSP_STREAM_URI 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_STREAM_URI \- RTSP stream URI .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_STREAM_URI, char URI); .fi .SH DESCRIPTION Set the stream \fIURI\fP to operate on by passing a char * . For example, a single session may be controlling \fIrtsp://foo/twister/audio\fP and \fIrtsp://foo/twister/video\fP and the application can switch to the appropriate stream using this option. If unset, libcurl defaults to operating on generic server options by passing \(aq\(aq in the place of the RTSP Stream URI. This option is distinct from \fICURLOPT_URL(3)\fP. When working with RTSP, the \fICURLOPT_RTSP_STREAM_URI(3)\fP indicates what URL to send to the server in the request header while the \fICURLOPT_URL(3)\fP indicates where to make the connection to. (e.g. the \fICURLOPT_URL(3)\fP for the above examples might be set to \fIrtsp://foo/twister\fP The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT \&"" .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); curl_easy_setopt(curl, CURLOPT_RTSP_STREAM_URI, "rtsp://foo.example.com/twister/video"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_RTSP_REQUEST (3), .BR CURLOPT_RTSP_TRANSPORT (3)	1.92 KB	2025-07-08 09:41
📄 CURLOPT_RTSP_TRANSPORT.3 .\" generated by cd2nroff 0.1 from CURLOPT_RTSP_TRANSPORT.md .TH CURLOPT_RTSP_TRANSPORT 3 "2025-06-27" libcurl .SH NAME CURLOPT_RTSP_TRANSPORT \- RTSP Transport: header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_RTSP_TRANSPORT, char transport); .fi .SH DESCRIPTION Pass a char pointer to tell libcurl what to pass for the Transport: header for this RTSP session. This is mainly a convenience method to avoid needing to set a custom Transport: header for every SETUP request. The application must set a Transport: header before issuing a SETUP request. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects rtsp only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "rtsp://example.com/"); curl_easy_setopt(curl, CURLOPT_RTSP_REQUEST, CURL_RTSPREQ_SETUP); curl_easy_setopt(curl, CURLOPT_RTSP_TRANSPORT, "RTP/AVP;unicast;client_port=4588-4589"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_RTSP_REQUEST (3), .BR CURLOPT_RTSP_SESSION_ID (3)	1.47 KB	2025-07-08 09:41
📄 CURLOPT_SASL_AUTHZID.3 .\" generated by cd2nroff 0.1 from CURLOPT_SASL_AUTHZID.md .TH CURLOPT_SASL_AUTHZID 3 "2025-06-27" libcurl .SH NAME CURLOPT_SASL_AUTHZID \- authorization identity (identity to act as) .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SASL_AUTHZID, char authzid); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated authorization identity (\fIauthzid\fP) for the transfer. Only applicable to the PLAIN SASL authentication mechanism where it is optional. When not specified only the authentication identity (\fIauthcid\fP) as specified by the username is sent to the server, along with the password. The server derives a \fIauthzid\fP from the \fIauthcid\fP when not provided, which it then uses internally. When the \fIauthzid\fP is specified, the use of which is server dependent, it can be used to access another user\(aqs inbox, that the user has been granted access to, or a shared mailbox for example. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT blank .SH PROTOCOLS This functionality affects imap only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com/"); curl_easy_setopt(curl, CURLOPT_USERNAME, "Kurt"); curl_easy_setopt(curl, CURLOPT_PASSWORD, "xipj3plmq"); curl_easy_setopt(curl, CURLOPT_SASL_AUTHZID, "Ursel"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.66.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PASSWORD (3), .BR CURLOPT_USERNAME (3), .BR CURLOPT_USERPWD (3)	1.96 KB	2025-07-08 09:41
📄 CURLOPT_SASL_IR.3 .\" generated by cd2nroff 0.1 from CURLOPT_SASL_IR.md .TH CURLOPT_SASL_IR 3 "2025-06-27" libcurl .SH NAME CURLOPT_SASL_IR \- send initial response in first packet .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SASL_IR, long enable); .fi .SH DESCRIPTION Pass a long. If the value is 1, curl sends the initial response to the server in the first authentication packet in order to reduce the number of ping pong requests. Only applicable to the following supporting SASL authentication mechanisms: Login * Plain * GSSAPI * NTLM * OAuth 2.0 Note: Whilst IMAP supports this option there is no need to explicitly set it, as libcurl can determine the feature itself when the server supports the SASL\-IR CAPABILITY. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects imap and smtp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "smtp://example.com/"); curl_easy_setopt(curl, CURLOPT_SASL_IR, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.31.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_AUTH (3), .BR CURLOPT_MAIL_FROM (3), .BR CURLOPT_SASL_AUTHZID (3)	1.4 KB	2025-07-08 09:41
📄 CURLOPT_SEEKDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_SEEKDATA.md .TH CURLOPT_SEEKDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_SEEKDATA \- pointer passed to the seek callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SEEKDATA, void pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the seek callback function. If you use the \fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you get as input. .SH DEFAULT If you do not set this, NULL is passed to the callback. .SH PROTOCOLS This functionality affects ftp, http and sftp .SH EXAMPLE .nf #include <unistd.h> /* for lseek() / struct data { int our_fd; }; static int seek_cb(void clientp, curl_off_t offset, int origin) { struct data d = (struct data )clientp; lseek(d->our_fd, offset, origin); return CURL_SEEKFUNC_OK; } int main(void) { struct data seek_data; CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); } } .fi .SH AVAILABILITY Added in curl 7.18.0 .SH RETURN VALUE .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_IOCTLFUNCTION (3), .BR CURLOPT_SEEKFUNCTION (3), .BR CURLOPT_STDERR (3)	1.21 KB	2025-07-08 09:41
📄 CURLOPT_SEEKFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SEEKFUNCTION.md .TH CURLOPT_SEEKFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream .SH SYNOPSIS .nf #include <curl/curl.h> /* These are the return codes for the seek callbacks / #define CURL_SEEKFUNC_OK 0 #define CURL_SEEKFUNC_FAIL 1 / fail the entire transfer / #define CURL_SEEKFUNC_CANTSEEK 2 / tell libcurl seeking cannot be done, so libcurl might try other means instead / int seek_callback(void clientp, curl_off_t offset, int origin); CURLcode curl_easy_setopt(CURL handle, CURLOPT_SEEKFUNCTION, seek_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This function gets called by libcurl to seek to a certain position in the input stream and can be used to fast forward a file in a resumed upload (instead of reading all uploaded bytes with the normal read function/callback). It is also called to rewind a stream when data has already been sent to the server and needs to be sent again. This may happen when doing an HTTP PUT or POST with a multi\-pass authentication method, or when an existing HTTP connection is reused too late and the server closes the connection. The function shall work like fseek(3) or lseek(3) and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl currently only passes SEEK_SET. \fIclientp\fP is the pointer you set with \fICURLOPT_SEEKDATA(3)\fP. The callback function must return \fICURL_SEEKFUNC_OK\fP on success, \fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or \fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. If you forward the input arguments directly to fseek(3) or lseek(3), note that the data type for \fIoffset\fP is not the same as defined for curl_off_t on many systems. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects ftp, http and sftp .SH EXAMPLE .nf #include <unistd.h> / for lseek / struct data { int our_fd; }; static int seek_cb(void clientp, curl_off_t offset, int origin) { struct data d = (struct data )clientp; lseek(d->our_fd, offset, origin); return CURL_SEEKFUNC_OK; } int main(void) { struct data seek_data; CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_SEEKFUNCTION, seek_cb); curl_easy_setopt(curl, CURLOPT_SEEKDATA, &seek_data); } } .fi .SH AVAILABILITY Added in curl 7.18.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_IOCTLFUNCTION (3), .BR CURLOPT_SEEKDATA (3), .BR CURLOPT_STDERR (3)	2.89 KB	2025-07-08 09:41
📄 CURLOPT_SERVER_RESPONSE_TIMEOUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_SERVER_RESPONSE_TIMEOUT.md .TH CURLOPT_SERVER_RESPONSE_TIMEOUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_SERVER_RESPONSE_TIMEOUT \- time allowed to wait for server response .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SERVER_RESPONSE_TIMEOUT, long timeout); .fi .SH DESCRIPTION Pass a long. Causes libcurl to set a \fItimeout\fP period (in seconds) on the amount of time that the server is allowed to take in order to send a response message for a command before the session is considered dead. While libcurl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP to a value smaller than \fICURLOPT_TIMEOUT(3)\fP. This option was formerly known as CURLOPT_FTP_RESPONSE_TIMEOUT. .SH DEFAULT None .SH PROTOCOLS This functionality affects ftp, imap, pop3, scp, sftp and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); /* wait no more than 23 seconds */ curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT, 23L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.20.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT (3), .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TIMEOUT (3)	1.67 KB	2025-07-08 09:41
📄 CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SERVER_RESPONSE_TIMEOUT_MS.md .TH CURLOPT_SERVER_RESPONSE_TIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SERVER_RESPONSE_TIMEOUT_MS \- time allowed to wait for server response .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, long timeout); .fi .SH DESCRIPTION Pass a long. Causes libcurl to set a \fItimeout\fP period (in milliseconds) on the amount of time that the server is allowed to take in order to send a response message for a command before the session is considered dead. While libcurl is waiting for a response, this value overrides \fICURLOPT_TIMEOUT(3)\fP. It is recommended that if used in conjunction with \fICURLOPT_TIMEOUT(3)\fP, you set \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP to a value smaller than \fICURLOPT_TIMEOUT(3)\fP. The maximum accepted value is 2147483648. This is the millisecond version of \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. .SH DEFAULT None .SH PROTOCOLS This functionality affects ftp, imap, pop3, scp, sftp and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/slow.txt"); /* wait no more than 237 milliseconds */ curl_easy_setopt(curl, CURLOPT_SERVER_RESPONSE_TIMEOUT_MS, 237L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 8.6.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT (3), .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TIMEOUT (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_SERVICE_NAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_SERVICE_NAME.md .TH CURLOPT_SERVICE_NAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_SERVICE_NAME \- authentication service name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SERVICE_NAME, char name); .fi .SH DESCRIPTION Pass a char pointer as parameter to a string holding the \fIname\fP of the service for DIGEST\-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default service names are "ftp", "HTTP", "imap", "ldap", "pop" and "smtp". This option allows you to change them. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT See above .SH PROTOCOLS This functionality affects ftp, http, imap, ldap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode ret; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SERVICE_NAME, "custom"); ret = curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.43.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYTYPE (3), .BR CURLOPT_PROXY_SERVICE_NAME (3)	1.45 KB	2025-07-08 09:41
📄 CURLOPT_SHARE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SHARE.md .TH CURLOPT_SHARE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SHARE \- share handle to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SHARE, CURLSH share); .fi .SH DESCRIPTION Pass a \fIshare\fP handle as a parameter. The share handle must have been created by a previous call to \fIcurl_share_init(3)\fP. Setting this option, makes this curl handle use the data from the shared handle instead of keeping the data to itself. This enables several curl handles to share data. If the curl handles are used simultaneously in multiple threads, you \fBMUST\fP use the locking methods in the share handle. See \fIcurl_share_setopt(3)\fP for details. If you add a share that is set to share cookies, your easy handle uses that cookie cache and get the cookie engine enabled. If you stop sharing an object that was using cookies (or change to another object that does not share cookies), the easy handle gets its cookie engine disabled. Data that the share object is not set to share is dealt with the usual way, as if no share was used. Set this option to NULL again to stop using that share object. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); CURL curl2 = curl_easy_init(); /* a second handle / if(curl) { CURLcode res; CURLSH shobject = curl_share_init(); curl_share_setopt(shobject, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_COOKIEFILE, ""); curl_easy_setopt(curl, CURLOPT_SHARE, shobject); res = curl_easy_perform(curl); curl_easy_cleanup(curl); /* the second handle shares cookies from the first */ curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/second"); curl_easy_setopt(curl2, CURLOPT_COOKIEFILE, ""); curl_easy_setopt(curl2, CURLOPT_SHARE, shobject); res = curl_easy_perform(curl2); curl_easy_cleanup(curl2); curl_share_cleanup(shobject); } } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_COOKIE (3), .BR CURLSHOPT_SHARE (3)	2.36 KB	2025-07-08 09:41
📄 CURLOPT_SOCKOPTDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_SOCKOPTDATA.md .TH CURLOPT_SOCKOPTDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_SOCKOPTDATA \- pointer to pass to sockopt callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SOCKOPTDATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static int sockopt_callback(void clientp, curl_socket_t curlfd, curlsocktype purpose) { int val = (int )clientp; setsockopt((int)curlfd, SOL_SOCKET, SO_RCVBUF, (const char )&val, sizeof(val)); return CURL_SOCKOPT_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; int recvbuffersize = 256 1024; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* call this function to set options for the socket */ curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE Returns \fICURLE_OK\fP if the option is supported, and \fICURLE_UNKNOWN_OPTION\fP if not. .SH SEE ALSO .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR CURLOPT_SOCKOPTFUNCTION (3)	1.48 KB	2025-07-08 09:41
📄 CURLOPT_SOCKOPTFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SOCKOPTFUNCTION.md .TH CURLOPT_SOCKOPTFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SOCKOPTFUNCTION \- callback for setting socket options .SH SYNOPSIS .nf #include <curl/curl.h> typedef enum { CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection / CURLSOCKTYPE_ACCEPT, / socket created by accept() call / CURLSOCKTYPE_LAST / never use / } curlsocktype; #define CURL_SOCKOPT_OK 0 #define CURL_SOCKOPT_ERROR 1 / causes libcurl to abort and return CURLE_ABORTED_BY_CALLBACK / #define CURL_SOCKOPT_ALREADY_CONNECTED 2 int sockopt_callback(void clientp, curl_socket_t curlfd, curlsocktype purpose); CURLcode curl_easy_setopt(CURL handle, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. When set, this callback function gets called by libcurl when the socket has been created, but before the connect call to allow applications to change specific socket options. The callback\(aqs \fIpurpose\fP argument identifies the exact purpose for this particular socket: \fICURLSOCKTYPE_IPCXN\fP for actively created connections or since 7.28.0 \fICURLSOCKTYPE_ACCEPT\fP for FTP when the connection was setup with PORT/EPSV (in earlier versions these sockets were not passed to this callback). Future versions of libcurl may support more purposes. libcurl passes the newly created socket descriptor to the callback in the \fIcurlfd\fP parameter so additional setsockopt() calls can be done at the user\(aqs discretion. The \fIclientp\fP pointer contains whatever user\-defined value set using the \fICURLOPT_SOCKOPTDATA(3)\fP function. Return \fICURL_SOCKOPT_OK\fP from the callback on success. Return \fICURL_SOCKOPT_ERROR\fP from the callback function to signal an unrecoverable error to the library and it closes the socket and returns \fICURLE_COULDNT_CONNECT\fP. Alternatively, the callback function can return \fICURL_SOCKOPT_ALREADY_CONNECTED\fP, to tell libcurl that the socket is already connected and then libcurl does no attempt to connect. This allows an application to pass in an already connected socket with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and then have this function make libcurl not attempt to connect (again). .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf / make libcurl use the already established socket 'sockfd' / static curl_socket_t opensocket(void clientp, curlsocktype purpose, struct curl_sockaddr address) { curl_socket_t sockfd; sockfd = (curl_socket_t )clientp; / the actual externally set socket is passed in via the OPENSOCKETDATA option / return sockfd; } static int sockopt_callback(void clientp, curl_socket_t curlfd, curlsocktype purpose) { /* This return code was added in libcurl 7.21.5 / return CURL_SOCKOPT_ALREADY_CONNECTED; } int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; int sockfd; /* our custom file descriptor / / libcurl thinks that you connect to the host * and port that you specify in the URL option. / curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999"); / call this function to get a socket / curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket); curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd); / call this function to set options for the socket */ curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR CURLOPT_SEEKFUNCTION (3), .BR CURLOPT_SOCKOPTDATA (3)	4.02 KB	2025-07-08 09:41
📄 CURLOPT_SOCKS5_AUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_AUTH.md .TH CURLOPT_SOCKS5_AUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_SOCKS5_AUTH \- methods for SOCKS5 proxy authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SOCKS5_AUTH, long bitmask); .fi .SH DESCRIPTION Pass a long as parameter, which is set to a bitmask, to tell libcurl which authentication method(s) are allowed for SOCKS5 proxy authentication. The only supported flags are \fICURLAUTH_BASIC\fP, which allows username/password authentication, \fICURLAUTH_GSSAPI\fP, which allows GSS\-API authentication, and \fICURLAUTH_NONE\fP, which allows no authentication. Set the actual username and password with the \fICURLOPT_PROXYUSERPWD(3)\fP option. .SH DEFAULT CURLAUTH_BASIC\|CURLAUTH_GSSAPI .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* request to use a SOCKS5 proxy / curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://user:pass@myproxy.com"); / enable username/password authentication only / curl_easy_setopt(curl, CURLOPT_SOCKS5_AUTH, (long)CURLAUTH_BASIC); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.55.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYTYPE (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_SOCKS5_GSSAPI_NEC.3 .\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_GSSAPI_NEC.md .TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "2025-06-27" libcurl .SH NAME CURLOPT_SOCKS5_GSSAPI_NEC \- SOCKS proxy GSSAPI negotiation protection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SOCKS5_GSSAPI_NEC, long nec); .fi .SH DESCRIPTION Pass a long set to 1 to enable or 0 to disable. As part of the GSSAPI negotiation a protection mode is negotiated. The RFC 1961 says in section 4.3/4.4 it should be protected, but the NEC reference implementation does not. If enabled, this option allows the unprotected exchange of the protection mode negotiation. .SH DEFAULT ? .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_NEC, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXY_SERVICE_NAME (3)	1.36 KB	2025-07-08 09:41
📄 CURLOPT_SOCKS5_GSSAPI_SERVICE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SOCKS5_GSSAPI_SERVICE.md .TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SOCKS5_GSSAPI_SERVICE \- SOCKS5 proxy authentication service name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SOCKS5_GSSAPI_SERVICE, char name); .fi .SH DESCRIPTION Deprecated since 7.49.0. Use \fICURLOPT_PROXY_SERVICE_NAME(3)\fP instead. Pass a char pointer as parameter to a string holding the \fIname\fP of the service. The default service name for a SOCKS5 server is \fIrcmd\fP. This option allows you to change it. The application does not have to keep the string around after setting this option. .SH DEFAULT See above .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "socks5://proxy"); curl_easy_setopt(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE, "rcmd-special"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH DEPRECATED Deprecated since 7.49.0 .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY (3), .BR CURLOPT_PROXYTYPE (3)	1.48 KB	2025-07-08 09:41
📄 CURLOPT_SSH_AUTH_TYPES.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_AUTH_TYPES.md .TH CURLOPT_SSH_AUTH_TYPES 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_AUTH_TYPES \- auth types for SFTP and SCP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_AUTH_TYPES, long bitmask); .fi .SH DESCRIPTION Pass a long set to a bitmask consisting of one or more of CURLSSH_AUTH_PUBLICKEY, CURLSSH_AUTH_PASSWORD, CURLSSH_AUTH_HOST, CURLSSH_AUTH_KEYBOARD and CURLSSH_AUTH_AGENT. Set \fICURLSSH_AUTH_ANY\fP to let libcurl pick a suitable one. Currently CURLSSH_AUTH_HOST has no effect. If CURLSSH_AUTH_AGENT is used, libcurl attempts to connect to ssh\-agent or pageant and let the agent attempt the authentication. .SH DEFAULT CURLSSH_AUTH_ANY (all available) .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_AUTH_TYPES, (long) CURLSSH_AUTH_PUBLICKEY \| CURLSSH_AUTH_KEYBOARD); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), .BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), .BR CURLOPT_SSH_PUBLIC_KEYFILE (3)	1.52 KB	2025-07-08 09:41
📄 CURLOPT_SSH_COMPRESSION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_COMPRESSION.md .TH CURLOPT_SSH_COMPRESSION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_COMPRESSION \- enable SSH compression .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_COMPRESSION, long enable); .fi .SH DESCRIPTION Pass a long as parameter set to 1L to enable or 0L to disable. Enables built\-in SSH compression. This is a request, not an order; the server may or may not do it. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com"); /* enable built-in compression / curl_easy_setopt(curl, CURLOPT_SSH_COMPRESSION, 1L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ACCEPT_ENCODING (3), .BR CURLOPT_TRANSFER_ENCODING (3)	1.15 KB	2025-07-08 09:41
📄 CURLOPT_SSH_HOSTKEYDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOSTKEYDATA.md .TH CURLOPT_SSH_HOSTKEYDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_HOSTKEYDATA \- pointer to pass to the SSH host key callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_HOSTKEYDATA, void pointer); .fi .SH DESCRIPTION Pass a void * as parameter. This \fIpointer\fP is passed along untouched to the callback set with \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf struct mine { void custom; }; static int hostkeycb(void clientp, /* CURLOPT_SSH_HOSTKEYDATA / int keytype, / CURLKHTYPE / const char key, /* host key to check / size_t keylen) / length of the key / { / 'clientp' points to the callback_data struct / / investigate the situation and return the correct value / return CURLKHMATCH_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct mine callback_data; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); curl_easy_perform(curl); } } .fi .SH NOTES Works only with the libssh2 backend. .SH AVAILABILITY Added in curl 7.84.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_HOSTKEYFUNCTION (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_SSH_HOSTKEYFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOSTKEYFUNCTION.md .TH CURLOPT_SSH_HOSTKEYFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_HOSTKEYFUNCTION \- callback to check host key .SH SYNOPSIS .nf #include <curl/curl.h> int keycallback(void clientp, int keytype, const char key, size_t keylen); CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_HOSTKEYFUNCTION, keycallback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. It overrides \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. This callback gets called when the verification of the SSH host key is needed. \fBkey\fP is \fBkeylen\fP bytes long and is the key to check. \fBkeytype\fP says what type it is, from the \fBCURLKHTYPE_\fP series in the \fBcurl_khtype\fP enum. \fBclientp\fP is a custom pointer set with \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. The callback MUST return one of the following return codes to tell libcurl how to act: .IP CURLKHMATCH_OK The host key is accepted, the connection should continue. .IP CURLKHMATCH_MISMATCH the host key is rejected, the connection is canceled. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf struct mine { void custom; }; int hostkeycb(void clientp, /* passed with CURLOPT_SSH_HOSTKEYDATA / int keytype, / CURLKHTYPE / const char key, /* host key to check / size_t keylen) / length of the key / { / 'clientp' points to the callback_data struct / / investigate the situation and return the correct value / return CURLKHMATCH_OK; } int main(void) { struct mine callback_data; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb); curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data); curl_easy_perform(curl); } } .fi .SH NOTES Work only with the libssh2 backend. .SH AVAILABILITY Added in curl 7.84.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_HOSTKEYDATA (3), .BR CURLOPT_SSH_KNOWNHOSTS (3)	2.33 KB	2025-07-08 09:41
📄 CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md .TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- MD5 checksum of SSH server public key .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, char md5); .fi .SH DESCRIPTION Pass a char pointer pointing to a string containing 32 hexadecimal digits. The string should be the 128 bit MD5 checksum of the remote host\(aqs public key, and libcurl aborts the connection to the host unless the MD5 checksum match. MD5 is a weak algorithm. We strongly recommend using \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP instead. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_MD5, "afe17cd62a0f3b61f1ab9cb22ba269a7"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.17.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_AUTH_TYPES (3), .BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3), .BR CURLOPT_SSH_KNOWNHOSTS (3), .BR CURLOPT_SSH_PUBLIC_KEYFILE (3)	1.71 KB	2025-07-08 09:41
📄 CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md .TH CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 \- SHA256 hash of SSH server public key .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, char sha256); .fi .SH DESCRIPTION Pass a char pointer pointing to a string containing a Base64\-encoded SHA256 hash of the remote host\(aqs public key. The transfer fails if the given hash does not match the hash the remote host provides. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, "NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ="); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH NOTES Requires the libssh2 backend. .SH AVAILABILITY Added in curl 7.80.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_AUTH_TYPES (3), .BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), .BR CURLOPT_SSH_PUBLIC_KEYFILE (3)	1.61 KB	2025-07-08 09:41
📄 CURLOPT_SSH_KEYDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_KEYDATA.md .TH CURLOPT_SSH_KEYDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_KEYDATA \- pointer passed to the SSH key callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_KEYDATA, void pointer); .fi .SH DESCRIPTION Pass a void * as parameter. This \fIpointer\fP is passed along verbatim to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf struct mine { void custom; }; static int keycb(CURL easy, const struct curl_khkey knownkey, const struct curl_khkey foundkey, enum curl_khmatch match, void clientp) { / 'clientp' points to the callback_data struct / / investigate the situation and return the correct value / return CURLKHSTAT_FINE_ADD_TO_FILE; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct mine callback_data; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_KEYDATA (3), .BR CURLOPT_SSH_KNOWNHOSTS (3)	1.61 KB	2025-07-08 09:41
📄 CURLOPT_SSH_KEYFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_KEYFUNCTION.md .TH CURLOPT_SSH_KEYFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic .SH SYNOPSIS .nf #include <curl/curl.h> enum curl_khstat { CURLKHSTAT_FINE_ADD_TO_FILE, CURLKHSTAT_FINE, CURLKHSTAT_REJECT, /* reject the connection, return an error / CURLKHSTAT_DEFER, / do not accept it, but we cannot answer right now. Causes a CURLE_PEER_FAILED_VERIFICATION error but the connection is left intact / CURLKHSTAT_FINE_REPLACE }; enum curl_khmatch { CURLKHMATCH_OK, / match / CURLKHMATCH_MISMATCH, / host found, key mismatch / CURLKHMATCH_MISSING, / no matching host/key found / }; struct curl_khkey { const char key; /* points to a null-terminated string encoded with base64 if len is zero, otherwise to the "raw" data / size_t len; enum curl_khtype keytype; }; int ssh_keycallback(CURL easy, const struct curl_khkey knownkey, const struct curl_khkey foundkey, enum curl_khmatch match, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_KEYFUNCTION, ssh_keycallback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. The callback is only called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set. This callback function gets passed the curl handle, the key from the known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP, info from libcurl on the matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return codes to tell libcurl how to act: .IP CURLKHSTAT_FINE_REPLACE The new host+key is accepted and libcurl replaces the old host+key into the known_hosts file before continuing with the connection. This also adds the new host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. (Added in 7.73.0) .IP CURLKHSTAT_FINE_ADD_TO_FILE The host+key is accepted and libcurl appends it to the known_hosts file before continuing with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. .IP CURLKHSTAT_FINE The host+key is accepted libcurl continues with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there. .IP CURLKHSTAT_REJECT The host+key is rejected. libcurl denies the connection to continue and it is closed. .IP CURLKHSTAT_DEFER The host+key is rejected, but the SSH connection is asked to be kept alive. This feature could be used when the app wants to return and act on the host+key situation and then retry without needing the overhead of setting it up from scratch again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf struct mine { void custom; }; static int keycb(CURL easy, const struct curl_khkey knownkey, const struct curl_khkey foundkey, enum curl_khmatch match, void clientp) { / 'clientp' points to the callback_data struct / / investigate the situation and return the correct value / return CURLKHSTAT_FINE_ADD_TO_FILE; } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct mine callback_data; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt"); curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb); curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data); curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_KEYDATA (3), .BR CURLOPT_SSH_KNOWNHOSTS (3)	4.46 KB	2025-07-08 09:41
📄 CURLOPT_SSH_KNOWNHOSTS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_KNOWNHOSTS.md .TH CURLOPT_SSH_KNOWNHOSTS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_KNOWNHOSTS \- filename holding the SSH known hosts .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_KNOWNHOSTS, char fname); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string holding the filename of the known_host file to use. The known_hosts file should use the OpenSSH file format. If this file is specified, libcurl only accepts connections with hosts that are known and present in that file, with a matching public key. Use \fICURLOPT_SSH_KEYFUNCTION(3)\fP to alter the default behavior on host and key matches and mismatches. We strongly suggest users doing SCP or SFTP transfers to set this option to make sure that the network communication is done with the intended server and not an impostor. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/clarkkent/.ssh/known_hosts"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_AUTH_TYPES (3), .BR CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 (3), .BR CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 (3)	1.84 KB	2025-07-08 09:41
📄 CURLOPT_SSH_PRIVATE_KEYFILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_PRIVATE_KEYFILE.md .TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_PRIVATE_KEYFILE \- private key file for SSH auth .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_PRIVATE_KEYFILE, char filename); .fi .SH DESCRIPTION Pass a char pointer pointing to a \fIfilename\fP for your private key. If not used, libcurl defaults to \fB$HOME/.ssh/id_rsa\fP or \fB$HOME/.ssh/id_dsa\fP if the HOME environment variable is set, and in the current directory if HOME is not set. If the file is password\-protected, set the password with \fICURLOPT_KEYPASSWD(3)\fP. The SSH library derives the public key from this private key when possible. If the SSH library cannot derive the public key from the private one and no public one is provided with \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP, the transfer fails. The application does not have to keep the string around after setting this option. .SH DEFAULT As explained above .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_PRIVATE_KEYFILE, "/home/clarkkent/.ssh/id_rsa"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "password"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_AUTH_TYPES (3), .BR CURLOPT_SSH_PUBLIC_KEYFILE (3)	1.78 KB	2025-07-08 09:41
📄 CURLOPT_SSH_PUBLIC_KEYFILE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSH_PUBLIC_KEYFILE.md .TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSH_PUBLIC_KEYFILE \- public key file for SSH auth .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSH_PUBLIC_KEYFILE, char filename); .fi .SH DESCRIPTION Pass a char pointer pointing to a \fIfilename\fP for your public key. If not used, libcurl defaults to \fB$HOME/.ssh/id_dsa.pub\fP if the HOME environment variable is set, and just "id_dsa.pub" in the current directory if HOME is not set. If NULL (or an empty string) is passed to this option, libcurl passes no public key to the SSH library, which then rather derives it from the private key. If the SSH library cannot derive the public key from the private one and no public one is provided, the transfer fails. The application does not have to keep the string around after setting this option. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects scp and sftp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); curl_easy_setopt(curl, CURLOPT_SSH_PUBLIC_KEYFILE, "/home/clarkkent/.ssh/id_rsa.pub"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY The "" trick was added in 7.26.0 .SH AVAILABILITY Added in curl 7.16.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSH_AUTH_TYPES (3), .BR CURLOPT_SSH_PRIVATE_KEYFILE (3)	1.7 KB	2025-07-08 09:41
📄 CURLOPT_SSLCERT.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLCERT.md .TH CURLOPT_SSLCERT 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLCERT \- SSL client certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLCERT, char cert); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the filename of your client certificate. The default format is \fIP12\fP on Secure Transport and \fIPEM\fP on other engines, and can be changed with \fICURLOPT_SSLCERTTYPE(3)\fP. With Secure Transport, this can also be the nickname of the certificate you wish to authenticate with as it is named in the security database. If you want to use a file from the current directory, please precede it with \fI./\fP prefix, in order to avoid confusion with a nickname. (Schannel only) Client certificates can be specified by a path expression to a certificate store. (You can import \fIPFX\fP to a store first). You can use \&"<store location>\\<store name>\\<thumbprint>" to refer to a certificate in the system certificates store, for example, \fB"CurrentUser\\MY\\934a7ac6f8a5d5"\fP. The thumbprint is usually a SHA\-1 hex string which you can see in certificate details. Following store locations are supported: \fBCurrentUser\fP, \fBLocalMachine\fP, \fBCurrentService\fP, \fBServices\fP, \fBCurrentUserGroupPolicy\fP, \fBLocalMachineGroupPolicy\fP, \fBLocalMachineEnterprise\fP. Schannel also support P12 certificate file, with the string \fIP12\fP specified with \fICURLOPT_SSLCERTTYPE(3)\fP. When using a client certificate, you most likely also need to provide a private key with \fICURLOPT_SSLKEY(3)\fP. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_KEYPASSWD (3), .BR CURLOPT_SSLCERTTYPE (3), .BR CURLOPT_SSLKEY (3)	2.78 KB	2025-07-08 09:41
📄 CURLOPT_SSLCERTTYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLCERTTYPE.md .TH CURLOPT_SSLCERTTYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLCERTTYPE \- type of client SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLCERTTYPE, char type); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER", except with Secure Transport or Schannel. OpenSSL (versions 0.9.3 and later), Secure Transport (on iOS 5 or later, or macOS 10.7 or later) and Schannel support "P12" for PKCS#12\-encoded files. GnuTLS supports P12 starting with curl 8.11.0. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL restores back to internal default. .SH DEFAULT \&"PEM" .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLKEY (3)	1.87 KB	2025-07-08 09:41
📄 CURLOPT_SSLCERT_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLCERT_BLOB.md .TH CURLOPT_SSLCERT_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLCERT_BLOB \- SSL client certificate from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLCERT_BLOB, struct curl_blob stblob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure, which contains (pointer and size) a client certificate. The format must be "P12" on Secure Transport or Schannel. The format must be "P12" or "PEM" on OpenSSL. The format must be \&"DER" or "PEM" on mbedTLS. The format must be specified with \fICURLOPT_SSLCERTTYPE(3)\fP. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. This option is an alternative to \fICURLOPT_SSLCERT(3)\fP which instead expects a filename as input. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, Secure Transport, mbedTLS and wolfSSL .SH EXAMPLE .nf extern char certificateData; / point to data / extern size_t filesize; / size of data / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob stblob; stblob.data = certificateData; stblob.len = filesize; stblob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &stblob); curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "P12"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_KEYPASSWD (3), .BR CURLOPT_SSLCERTTYPE (3), .BR CURLOPT_SSLKEY (3)	2.08 KB	2025-07-08 09:41
📄 CURLOPT_SSLENGINE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLENGINE.md .TH CURLOPT_SSLENGINE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLENGINE \- Set SSL engine or provider .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLENGINE, char id); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It is used as the identifier for the \fIengine\fP or \fIprovider\fP you want to use for your private key. OpenSSL 1 had engines, OpenSSL 3 has providers. The application does not have to keep the string around after setting this option. When asking libcurl to use a provider, the application can also optionally provide a \fIproperty\fP, a set of name value pairs. Such a property can be specified separated from the name with a colon (\fI:\fP). Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE CURLE_OK \- Engine found. CURLE_SSL_ENGINE_NOTFOUND \- Engine not found, or OpenSSL was not built with engine support. CURLE_SSL_ENGINE_INITFAILED \- Engine found but initialization failed. CURLE_NOT_BUILT_IN \- Option not built in, OpenSSL is not the SSL backend. CURLE_UNKNOWN_OPTION \- Option not recognized. CURLE_OUT_OF_MEMORY \- Insufficient heap space. .SH SEE ALSO .BR CURLINFO_SSL_ENGINES (3), .BR CURLOPT_SSLENGINE_DEFAULT (3), .BR CURLOPT_SSLKEY (3)	1.88 KB	2025-07-08 09:41
📄 CURLOPT_SSLENGINE_DEFAULT.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLENGINE_DEFAULT.md .TH CURLOPT_SSLENGINE_DEFAULT 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLENGINE_DEFAULT \- make SSL engine default .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLENGINE_DEFAULT, long val); .fi .SH DESCRIPTION Pass a long set to 1 to make the already specified crypto engine the default for (asymmetric) crypto operations. This option has no effect unless set after \fICURLOPT_SSLENGINE(3)\fP. .SH DEFAULT None .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLENGINE, "dynamic"); curl_easy_setopt(curl, CURLOPT_SSLENGINE_DEFAULT, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE CURLE_OK \- Engine set as default. CURLE_SSL_ENGINE_SETFAILED \- Engine could not be set as default. CURLE_NOT_BUILT_IN \- Option not built in, OpenSSL is not the SSL backend. CURLE_UNKNOWN_OPTION \- Option not recognized. CURLE_OUT_OF_MEMORY \- Insufficient heap space. .SH SEE ALSO .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLENGINE (3)	1.4 KB	2025-07-08 09:41
📄 CURLOPT_SSLKEY.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLKEY.md .TH CURLOPT_SSLKEY 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLKEY \- private key file for TLS and SSL client cert .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLKEY, char keyfile); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the filename of your private key. The default format is "PEM" and can be changed with \fICURLOPT_SSLKEYTYPE(3)\fP. (Windows, iOS and macOS) This option is ignored by Secure Transport and Schannel SSL backends because they expect the private key to be already present in the key\-chain or PKCS#12 file containing the certificate. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, Schannel, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLKEYTYPE (3), .BR CURLOPT_SSLKEY_BLOB (3)	1.83 KB	2025-07-08 09:41
📄 CURLOPT_SSLKEYTYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLKEYTYPE.md .TH CURLOPT_SSLKEYTYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLKEYTYPE \- type of the private key file .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLKEYTYPE, char type); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER", "ENG" and \&"PROV". The format "ENG" enables you to load the private key from a crypto engine. In this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the engine. You have to set the crypto engine with \fICURLOPT_SSLENGINE(3)\fP. The format "PROV" enables you to load the private key from a crypto provider (Added in 8.12.0). In this case \fICURLOPT_SSLKEY(3)\fP is used as an identifier passed to the provider. The "DER" format does not work with OpenSSL. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to internal default. .SH DEFAULT \&"PEM" .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSLCERT, "client.pem"); curl_easy_setopt(curl, CURLOPT_SSLKEY, "key.pem"); curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9.3 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLKEYTYPE (3), .BR CURLOPT_SSLCERT (3), .BR CURLOPT_SSLKEY (3)	2.09 KB	2025-07-08 09:41
📄 CURLOPT_SSLKEY_BLOB.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLKEY_BLOB.md .TH CURLOPT_SSLKEY_BLOB 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLKEY_BLOB \- private key for client cert from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLKEY_BLOB, struct curl_blob blob); .fi .SH DESCRIPTION Pass a pointer to a curl_blob structure, which contains information (pointer and size) for a private key. Compatible with OpenSSL. The format (like "PEM") must be specified with \fICURLOPT_SSLKEYTYPE(3)\fP. If the blob is initialized with the flags member of struct curl_blob set to CURL_BLOB_COPY, the application does not have to keep the buffer around after setting this. This option is an alternative to \fICURLOPT_SSLKEY(3)\fP which instead expects a filename as input. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL and wolfSSL .SH EXAMPLE .nf extern char certificateData; / point to cert / extern size_t filesize; / size of cert / extern char privateKeyData; /* point to key / extern size_t privateKeySize; / size of key / int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_blob blob; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); blob.data = certificateData; blob.len = filesize; blob.flags = CURL_BLOB_COPY; curl_easy_setopt(curl, CURLOPT_SSLCERT_BLOB, &blob); curl_easy_setopt(curl, CURLOPT_SSLCERTTYPE, "PEM"); blob.data = privateKeyData; blob.len = privateKeySize; curl_easy_setopt(curl, CURLOPT_SSLKEY_BLOB, &blob); curl_easy_setopt(curl, CURLOPT_KEYPASSWD, "s3cret"); curl_easy_setopt(curl, CURLOPT_SSLKEYTYPE, "PEM"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.71.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLKEY (3), .BR CURLOPT_SSLKEYTYPE (3)	2.17 KB	2025-07-08 09:41
📄 CURLOPT_SSLVERSION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSLVERSION.md .TH CURLOPT_SSLVERSION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSLVERSION \- preferred TLS/SSL version .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSLVERSION, long version); .fi .SH DESCRIPTION Pass a long as parameter to control which version range of SSL/TLS versions to use. The SSL and TLS versions have typically developed from the most insecure version to be more and more secure in this order through history: SSL v2, SSLv3, TLS v1.0, TLS v1.1, TLS v1.2 and the most recent TLS v1.3. Use one of the available defines for this purpose. The available options are: .IP CURL_SSLVERSION_DEFAULT The default acceptable version range. The minimum acceptable version is by default TLS v1.0 since 7.39.0 (unless the TLS library has a stricter rule). .IP CURL_SSLVERSION_TLSv1 TLS v1.0 or later .IP CURL_SSLVERSION_SSLv2 SSL v2 \- refused .IP CURL_SSLVERSION_SSLv3 SSL v3 \- refused .IP CURL_SSLVERSION_TLSv1_0 TLS v1.0 or later (Added in 7.34.0) .IP CURL_SSLVERSION_TLSv1_1 TLS v1.1 or later (Added in 7.34.0) .IP CURL_SSLVERSION_TLSv1_2 TLS v1.2 or later (Added in 7.34.0) .IP CURL_SSLVERSION_TLSv1_3 TLS v1.3 or later (Added in 7.52.0) .PP The maximum TLS version can be set by using \fIone\fP of the CURL_SSLVERSION_MAX_ macros below. It is also possible to OR \fIone\fP of the CURL_SSLVERSION_ macros with \fIone\fP of the CURL_SSLVERSION_MAX_ macros. .IP CURL_SSLVERSION_MAX_DEFAULT The flag defines the maximum supported TLS version by libcurl, or the default value from the SSL library is used. libcurl uses a sensible default maximum, which was TLS v1.2 up to before 7.61.0 and is TLS v1.3 since then \- assuming the TLS library support it. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_0 The flag defines maximum supported TLS version as TLS v1.0. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_1 The flag defines maximum supported TLS version as TLS v1.1. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_2 The flag defines maximum supported TLS version as TLS v1.2. (Added in 7.54.0) .IP CURL_SSLVERSION_MAX_TLSv1_3 The flag defines maximum supported TLS version as TLS v1.3. (Added in 7.54.0) .PP In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were documented to allow \fIonly\fP the specified TLS version, but behavior was inconsistent depending on the TLS library. .SH DEFAULT CURL_SSLVERSION_DEFAULT .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* ask libcurl to use TLS version 1.0 or later / curl_easy_setopt(curl, CURLOPT_SSLVERSION, (long)CURL_SSLVERSION_TLSv1); / Perform the request */ curl_easy_perform(curl); } } .fi .SH HISTORY SSLv2 is disabled by default since 7.18.1. Other SSL versions availability may vary depending on which backend libcurl has been built to use. SSLv3 is disabled by default since 7.39.0. SSLv2 and SSLv3 are refused completely since curl 7.77.0 Since 8.10.0 wolfSSL is fully supported. Before 8.10.0 the MAX macros were not supported with wolfSSL and the other macros did not set a minimum, but restricted the TLS version to only the specified one. Rustls support added in 8.10.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_IPRESOLVE (3), .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_USE_SSL (3)	3.69 KB	2025-07-08 09:41
📄 CURLOPT_SSL_CIPHER_LIST.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_CIPHER_LIST.md .TH CURLOPT_SSL_CIPHER_LIST 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_CIPHER_LIST \- ciphers to use for TLS .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_CIPHER_LIST, char list); .fi .SH DESCRIPTION Pass a char pointer, pointing to a null\-terminated string holding the list of cipher suites to use for the TLS 1.2 (1.1, 1.0) connection. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. For setting TLS 1.3 ciphers see \fICURLOPT_TLS13_CIPHERS(3)\fP. A valid example of a cipher list with OpenSSL is: .nf "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" .fi For Schannel, you can use this option to set algorithms but not specific cipher suites. Refer to the ciphers lists document for algorithms. GnuTLS has the concept of a [priority string](https://gnutls.org/manual/html_node/Priority\-Strings.html) which has its own syntax and keywords. The string set via \fICURLOPT_SSL_CIPHER_LIST(3)\fP directly influences the priority setting. Find more details about cipher lists on this URL: https://curl.se/docs/ssl\-ciphers.html The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL, use built\-in list .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, GnuTLS, OpenSSL, Schannel, Secure Transport, mbedTLS, rustls and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSL_CIPHER_LIST, "ECDHE-ECDSA-CHACHA20-POLY1305:" "ECDHE-RSA-CHACHA20-POLY1305"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY OpenSSL support added in 7.9. wolfSSL support added in 7.53.0. Schannel support added in 7.61.0. Secure Transport support added in 7.77.0. BearSSL support added in 7.83.0. mbedTLS support added in 8.8.0. Rustls support added in 8.10.0. Since curl 8.10.0 returns CURLE_NOT_BUILT_IN when not supported. .SH AVAILABILITY Added in curl 7.9 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), .BR CURLOPT_PROXY_TLS13_CIPHERS (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_TLS13_CIPHERS (3), .BR CURLOPT_USE_SSL (3)	2.81 KB	2025-07-08 09:41
📄 CURLOPT_SSL_CTX_DATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_CTX_DATA.md .TH CURLOPT_SSL_CTX_DATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_CTX_DATA \- pointer passed to SSL context callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_CTX_DATA, void pointer); .fi .SH DESCRIPTION Data \fIpointer\fP to pass to the ssl context callback set by the option \fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you get as third parameter. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf /* OpenSSL specific / #include <openssl/ssl.h> #include <curl/curl.h> #include <stdio.h> static CURLcode sslctx_function(CURL curl, void sslctx, void parm) { X509_STORE store; X509 cert = NULL; BIO bio; char mypem = parm; /* get a BIO / bio = BIO_new_mem_buf(mypem, -1); / use it to read the PEM formatted certificate from memory into an * X509 structure that SSL can use / PEM_read_bio_X509(bio, &cert, 0, NULL); if(!cert) printf("PEM_read_bio_X509 failed...\\n"); / get a pointer to the X509 certificate store (which may be empty) / store = SSL_CTX_get_cert_store((SSL_CTX )sslctx); /* add our certificate to this store / if(X509_STORE_add_cert(store, cert) == 0) printf("error adding certificate\\n"); / decrease reference counts / X509_free(cert); BIO_free(bio); / all set to go / return CURLE_OK; } int main(void) { CURL ch; CURLcode rv; char mypem = / example CA cert PEM - shortened / "-----BEGIN CERTIFICATE-----\\n" "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" "-----END CERTIFICATE-----\\n"; curl_global_init(CURL_GLOBAL_ALL); ch = curl_easy_init(); curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM"); curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, sslctx_function); curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); if(!rv) printf("* transfer succeeded \\n"); else printf(" transfer failed *\\n"); curl_easy_cleanup(ch); curl_global_cleanup(); return rv; } .fi .SH HISTORY Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL, in 7.54.0 for mbedTLS, in 7.83.0 in BearSSL. .SH AVAILABILITY Added in curl 7.10.6 .SH RETURN VALUE CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN \- Not supported by the SSL backend CURLE_UNKNOWN_OPTION .SH SEE ALSO .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CTX_FUNCTION (3)	3.1 KB	2025-07-08 09:41
📄 CURLOPT_SSL_CTX_FUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_CTX_FUNCTION.md .TH CURLOPT_SSL_CTX_FUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_CTX_FUNCTION \- SSL context callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode ssl_ctx_callback(CURL curl, void ssl_ctx, void clientp); CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_CTX_FUNCTION, ssl_ctx_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behavior of the SSL initialization. The \fIssl_ctx\fP parameter is a pointer to the SSL library\(aqs \fISSL_CTX\fP for OpenSSL or wolfSSL, a pointer to \fImbedtls_ssl_config\fP for mbedTLS or a pointer to \fIbr_ssl_client_context\fP for BearSSL. If an error is returned from the callback no attempt to establish a connection is made and the perform operation returns the callback\(aqs error code. Set the \fIclientp\fP argument passed in to this callback with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. This function gets called for all new connections made to a server, during the SSL negotiation. While \fIssl_ctx\fP points to a newly initialized object each time, the pointer may still be the same as in a prior call. To use this callback, a non\-trivial amount of knowledge of your SSL library is necessary. For example, you can use this function to call library\-specific callbacks to add additional validation code for certificates, and even to change the actual URI of an HTTPS request. For OpenSSL, asynchronous certificate verification via \fISSL_set_retry_verify\fP is supported. (Added in 8.3.0) The \fICURLOPT_SSL_CTX_FUNCTION(3)\fP callback allows the application to reach in and modify SSL details in the connection without libcurl itself knowing anything about it, which then subsequently can lead to libcurl unknowingly reusing SSL connections with different properties. To remedy this you may set \fICURLOPT_FORBID_REUSE(3)\fP from the callback function. If you are using DNS\-over\-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP then this callback is also called for those transfers and the curl handle is set to an internal handle. \fBThis behavior is subject to change.\fP We recommend setting \fICURLOPT_PRIVATE(3)\fP on your curl handle so you can identify it correctly in the context callback. If you have a reason to modify DoH SSL context please let us know on the curl\-library mailing list because we are considering removing this capability. libcurl does not guarantee the lifetime of the passed in object once this callback function has returned. Your application must not assume that it can keep using the SSL context or data derived from it once this function is completed. For libcurl builds using TLS backends that support CA caching and \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP is not set to zero, multiple calls to this callback may be done with the same CA store in memory. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf /* OpenSSL specific / #include <openssl/ssl.h> #include <curl/curl.h> #include <stdio.h> static CURLcode sslctx_function(CURL curl, void sslctx, void parm) { X509_STORE store; X509 cert = NULL; BIO bio; char mypem = parm; /* get a BIO / bio = BIO_new_mem_buf(mypem, -1); / use it to read the PEM formatted certificate from memory into an * X509 structure that SSL can use / PEM_read_bio_X509(bio, &cert, 0, NULL); if(!cert) printf("PEM_read_bio_X509 failed...\\n"); / get a pointer to the X509 certificate store (which may be empty) / store = SSL_CTX_get_cert_store((SSL_CTX )sslctx); /* add our certificate to this store / if(X509_STORE_add_cert(store, cert) == 0) printf("error adding certificate\\n"); / decrease reference counts / X509_free(cert); BIO_free(bio); / all set to go / return CURLE_OK; } int main(void) { CURL ch; CURLcode rv; char mypem = / example CA cert PEM - shortened / "-----BEGIN CERTIFICATE-----\\n" "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\\n" "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\\n" "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\\n" "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\\n" "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\\n" "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\\n" "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" "-----END CERTIFICATE-----\\n"; curl_global_init(CURL_GLOBAL_ALL); ch = curl_easy_init(); curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM"); curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, sslctx_function); curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); rv = curl_easy_perform(ch); if(!rv) printf("* transfer succeeded \\n"); else printf(" transfer failed *\\n"); curl_easy_cleanup(ch); curl_global_cleanup(); return rv; } .fi .SH AVAILABILITY Added in curl 7.10.6 .SH RETURN VALUE CURLE_OK if supported; or an error such as: CURLE_NOT_BUILT_IN \- Not supported by the SSL backend .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_CAINFO_BLOB (3), .BR CURLOPT_CA_CACHE_TIMEOUT (3), .BR CURLOPT_SSL_CTX_DATA (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	5.66 KB	2025-07-08 09:41
📄 CURLOPT_SSL_EC_CURVES.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_EC_CURVES.md .TH CURLOPT_SSL_EC_CURVES 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_EC_CURVES \- key exchange curves .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_EC_CURVES, char list); .fi .SH DESCRIPTION Pass a string as parameter with a colon delimited list of Elliptic curve (EC) algorithms. This option defines the client\(aqs key exchange algorithms in the SSL handshake (if the SSL backend libcurl is built to use supports it). The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore back to internal default. .SH DEFAULT \&"", embedded in SSL backend .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSL_EC_CURVES, "X25519:P-521"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.73.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_SSL_OPTIONS (3), .BR CURLOPT_TLS13_CIPHERS (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_SSL_ENABLE_ALPN.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_ENABLE_ALPN.md .TH CURLOPT_SSL_ENABLE_ALPN 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_ENABLE_ALPN \- Application Layer Protocol Negotiation .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_ENABLE_ALPN, long npn); .fi .SH DESCRIPTION Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This option enables/disables ALPN in the SSL handshake (if the SSL backend libcurl is built to use supports it), which can be used to negotiate http2. .SH DEFAULT 1, enabled .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_ALPN, 0L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.36.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSL_ENABLE_NPN (3), .BR CURLOPT_SSL_OPTIONS (3)	1.28 KB	2025-07-08 09:41
📄 CURLOPT_SSL_ENABLE_NPN.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_ENABLE_NPN.md .TH CURLOPT_SSL_ENABLE_NPN 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_ENABLE_NPN \- use NPN .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_ENABLE_NPN, long npn); .fi .SH DESCRIPTION Deprecated since 7.86.0 Setting this option has no function. Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. This option enables/disables NPN in the SSL handshake (if the SSL backend libcurl is built to use supports it), which can be used to negotiate http2. .SH DEFAULT 1, enabled .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSL_ENABLE_NPN, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH DEPRECATED Deprecated since 7.86.0 .SH AVAILABILITY Added in curl 7.36.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSL_ENABLE_ALPN (3), .BR CURLOPT_SSL_OPTIONS (3)	1.35 KB	2025-07-08 09:41
📄 CURLOPT_SSL_FALSESTART.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_FALSESTART.md .TH CURLOPT_SSL_FALSESTART 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_FALSESTART \- TLS false start .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_FALSESTART, long enable); .fi .SH DESCRIPTION Pass a long as parameter set to 1L to enable or 0 to disable. This option determines whether libcurl should use false start during the TLS handshake. False start is a mode where a TLS client starts sending application data before verifying the server\(aqs Finished message, thus saving a round trip when performing a full handshake. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: Secure Transport .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.42.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TCP_FASTOPEN (3)	1.31 KB	2025-07-08 09:41
📄 CURLOPT_SSL_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_OPTIONS.md .TH CURLOPT_SSL_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_OPTIONS \- SSL behavior options .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_OPTIONS, long bitmask); .fi .SH DESCRIPTION Pass a long with a bitmask to tell libcurl about specific SSL behaviors. Available bits: .IP CURLSSLOPT_ALLOW_BEAST Tells libcurl to not attempt to use any workarounds for a security flaw in the SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0, the SSL layer libcurl uses may use a work\-around for this flaw although it might cause interoperability problems with some (older) SSL implementations. WARNING: avoiding this work\-around lessens the security, and by setting this option to 1 you ask for exactly that. This option is only supported for Secure Transport and OpenSSL. .IP CURLSSLOPT_NO_REVOKE Tells libcurl to disable certificate revocation checks for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library), with an exception in the case of Windows\(aq Untrusted Publishers block list which it seems cannot be bypassed. (Added in 7.44.0) .IP CURLSSLOPT_NO_PARTIALCHAIN Tells libcurl to not accept "partial" certificate chains, which it otherwise does by default. This option is only supported for OpenSSL and fails the certificate verification if the chain ends with an intermediate certificate and not with a root cert. (Added in 7.68.0) .IP CURLSSLOPT_REVOKE_BEST_EFFORT Tells libcurl to ignore certificate revocation checks in case of missing or offline distribution points for those SSL backends where such behavior is present. This option is only supported for Schannel (the native Windows SSL library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes precedence. (Added in 7.70.0) .IP CURLSSLOPT_NATIVE_CA Tell libcurl to use the operating system\(aqs native CA store for certificate verification. This option is independent of other CA certificate locations set at run time or build time. Those locations are searched in addition to the native CA store. Works with wolfSSL on Windows, Linux (Debian, Ubuntu, Gentoo, Fedora, RHEL), macOS, Android and iOS (added in 8.3.0); with GnuTLS (added in 8.5.0) and with OpenSSL and its forks (LibreSSL, BoringSSL, etc) on Windows (Added in 7.71.0). This works with rustls on Windows, macOS, Android and iOS. On Linux it is equivalent to using the Mozilla CA certificate bundle. When used with rustls _only_ the native CA store is consulted, not other locations set at run time or build time. (Added in 8.13.0) .IP CURLSSLOPT_AUTO_CLIENT_CERT Tell libcurl to automatically locate and use a client certificate for authentication, when requested by the server. This option is only supported for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the default behavior in libcurl with Schannel. Since the server can request any certificate that supports client authentication in the OS certificate store it could be a privacy violation and unexpected. (Added in 7.77.0) .IP CURLSSLOPT_EARLYDATA Tell libcurl to try sending application data as TLS1.3 early data. This option is supported for GnuTLS, wolfSSL, quictls and OpenSSL (but not BoringSSL or AWS\-LC). It works on TCP and QUIC connections using ngtcp2. This option works on a best effort basis, in cases when it wasn\(aqt possible to send early data the request is resent normally post\-handshake. This option does not work when using QUIC. (Added in 8.11.0 for GnuTLS and 8.13.0 for wolfSSL, quictls and OpenSSL) .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* weaken TLS only for use with silly servers */ curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, (long)CURLSSLOPT_ALLOW_BEAST \| CURLSSLOPT_NO_REVOKE); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.25.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSL_OPTIONS (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3)	4.46 KB	2025-07-08 09:41
📄 CURLOPT_SSL_SESSIONID_CACHE.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_SESSIONID_CACHE.md .TH CURLOPT_SSL_SESSIONID_CACHE 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_SESSIONID_CACHE \- use the SSL session\-ID cache .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_SESSIONID_CACHE, long enabled); .fi .SH DESCRIPTION Pass a long set to 0 to disable libcurl\(aqs use of SSL session\-ID caching. Set this to 1 to enable it. By default all transfers are done using the cache enabled. While nothing ever should get hurt by attempting to reuse SSL session\-IDs, there seem to be or have been broken SSL implementations in the wild that may require you to disable this in order for you to succeed. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* switch off session-id use */ curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DNS_CACHE_TIMEOUT (3), .BR CURLOPT_MAXAGE_CONN (3), .BR CURLOPT_MAXLIFETIME_CONN (3), .BR CURLOPT_SSLVERSION (3)	1.56 KB	2025-07-08 09:41
📄 CURLOPT_SSL_SIGNATURE_ALGORITHMS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_SIGNATURE_ALGORITHMS.md .TH CURLOPT_SSL_SIGNATURE_ALGORITHMS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_SIGNATURE_ALGORITHMS \- signature algorithms to use for TLS .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_SIGNATURE_ALGORITHMS, char list); .fi .SH DESCRIPTION Pass a char pointer, pointing to a null\-terminated string holding the list of signature algorithms to use for the TLS connection. The list must be syntactically correct, it consists of one or more signature algorithm strings separated by colons. A valid example of a signature algorithms list with OpenSSL is: .nf "DSA+SHA256:rsa_pss_pss_sha256" .fi The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. Works with OpenSSL and its BoringSSL fork (added in 8.14.0). .SH DEFAULT NULL, use built\-in list .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_SSL_SIGNATURE_ALGORITHMS, "DSA+SHA256:rsa_pss_pss_sha256"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY OpenSSL support added in 8.14.0. .SH AVAILABILITY Added in curl 8.14.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_SSL_EC_CURVES (3), .BR CURLOPT_USE_SSL (3)	1.91 KB	2025-07-08 09:41
📄 CURLOPT_SSL_VERIFYHOST.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYHOST.md .TH CURLOPT_SSL_VERIFYHOST 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_VERIFYHOST \- verify the certificate\(aqs name against host .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_VERIFYHOST, long verify); .fi .SH DESCRIPTION Pass a long set to 2L to make libcurl verify the host in the server\(aqs TLS certificate. When negotiating a TLS connection, the server sends a certificate indicating its identity. When \fICURLOPT_SSL_VERIFYHOST(3)\fP is set to 1 or 2, the server certificate must indicate that it was made for the hostname or address curl connects to, or the connection fails. Simply put, it means it has to have the same name in the certificate as is used in the URL you operate against. curl considers the server the intended one when the Common Name field or a Subject Alternate Name field in the certificate matches the hostname in the URL to which you told curl to connect. When the \fIverify\fP value is 0, the connection succeeds regardless of the names in the certificate. Use that ability with caution, This option controls checking the server\(aqs certificate\(aqs claimed identity. The separate \fICURLOPT_SSL_VERIFYPEER(3)\fP options enables/disables verification that the certificate is signed by a trusted Certificate Authority. WARNING: disabling verification of the certificate allows bad guys to man\-in\-the\-middle the communication without you knowing it. Disabling verification makes the communication insecure. Just having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end\-point. When libcurl uses secure protocols it trusts responses and allows for example HSTS and Alt\-Svc information to be stored and used subsequently. Disabling certificate verification can make libcurl trust and use such information from malicious servers. .SH MATCHING A certificate can have the name as a wildcard. The only asterisk (\fI\fP) must then be the left\-most character and it must be followed by a period. The wildcard must further contain more than one period as it cannot be set for a top\-level domain. A certificate can be set for a numerical IP address (IPv4 or IPv6), but then it should be a Subject Alternate Name kind and its type should correctly identify the field as an IP address. .SH LIMITATIONS Secure Transport: If \fIverify\fP value is 0, then SNI is also disabled. SNI is a TLS extension that sends the hostname to the server. The server may use that information to do such things as sending back a specific certificate for the hostname, or forwarding the request to a specific origin server. Some hostnames may be inaccessible if SNI is not sent. .SH DEFAULT 2 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Set the default value: strict name check please */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.8.1 .SH HISTORY In 7.28.0 and earlier: the value 1 was treated as a debug option of some sorts, not supported anymore due to frequently leading to programmer mistakes. From 7.28.1 to 7.65.3: setting it to 1 made \fIcurl_easy_setopt(3)\fP return an error and leaving the flag untouched. From 7.66.0: libcurl treats 1 and 2 to this option the same. .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_PINNEDPUBLICKEY (3), .BR CURLOPT_SSL_VERIFYPEER (3)	3.8 KB	2025-07-08 09:41
📄 CURLOPT_SSL_VERIFYPEER.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYPEER.md .TH CURLOPT_SSL_VERIFYPEER 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_VERIFYPEER \- verify the peer\(aqs SSL certificate .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_VERIFYPEER, long verify); .fi .SH DESCRIPTION Pass a long as parameter to enable or disable. This option determines whether curl verifies the authenticity of the peer\(aqs certificate. A value of 1 means curl verifies; 0 (zero) means it does not. When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. curl verifies whether the certificate is authentic, i.e. that you can trust that the server is who the certificate says it is. This trust is based on a chain of digital signatures, rooted in certification authority (CA) certificates you supply. curl uses a default bundle of CA certificates (the path for that is determined at build time) and you can specify alternate certificates with the \fICURLOPT_CAINFO(3)\fP option or the \fICURLOPT_CAPATH(3)\fP option. When \fICURLOPT_SSL_VERIFYPEER(3)\fP is enabled, and the verification fails to prove that the certificate is signed by a CA, the connection fails. When this option is disabled (set to zero), the CA certificates are not loaded and the peer certificate verification is simply skipped. Authenticating the certificate is not enough to be sure about the server. You typically also want to ensure that the server is the server you mean to be talking to. Use \fICURLOPT_SSL_VERIFYHOST(3)\fP for that. The check that the host name in the certificate is valid for the hostname you are connecting to is done independently of the \fICURLOPT_SSL_VERIFYPEER(3)\fP option. WARNING: disabling verification of the certificate allows bad guys to man\-in\-the\-middle the communication without you knowing it. Disabling verification makes the communication insecure. Just having encryption on a transfer is not enough as you cannot be sure that you are communicating with the correct end\-point. When libcurl uses secure protocols it trusts responses and allows for example HSTS and Alt\-Svc information to be stored and used subsequently. Disabling certificate verification can make libcurl trust and use such information from malicious servers. .SH DEFAULT 1 \- enabled .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. All TLS backends support this option. .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* Set the default value: strict certificate check please */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CAINFO (3), .BR CURLINFO_CAPATH (3), .BR CURLOPT_CAINFO (3), .BR CURLOPT_PROXY_SSL_VERIFYHOST (3), .BR CURLOPT_PROXY_SSL_VERIFYPEER (3), .BR CURLOPT_SSL_VERIFYHOST (3)	3.14 KB	2025-07-08 09:41
📄 CURLOPT_SSL_VERIFYSTATUS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SSL_VERIFYSTATUS.md .TH CURLOPT_SSL_VERIFYSTATUS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SSL_VERIFYSTATUS \- verify the certificate\(aqs status .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SSL_VERIFYSTATUS, long verify); .fi .SH DESCRIPTION Pass a long as parameter set to 1 to enable or 0 to disable. This option determines whether libcurl verifies the status of the server cert using the "Certificate Status Request" TLS extension (aka. OCSP stapling). Note that if this option is enabled but the server does not support the TLS extension, the verification fails. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* ask for OCSP stapling */ curl_easy_setopt(curl, CURLOPT_SSL_VERIFYSTATUS, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.41.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CAINFO (3), .BR CURLOPT_SSL_VERIFYHOST (3), .BR CURLOPT_SSL_VERIFYPEER (3)	1.47 KB	2025-07-08 09:41
📄 CURLOPT_STDERR.3 .\" generated by cd2nroff 0.1 from CURLOPT_STDERR.md .TH CURLOPT_STDERR 3 "2025-06-27" libcurl .SH NAME CURLOPT_STDERR \- redirect stderr to another stream .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_STDERR, FILE stream); .fi .SH DESCRIPTION Pass a FILE * as parameter. Tell libcurl to use this \fIstream\fP instead of stderr when showing the progress meter and displaying \fICURLOPT_VERBOSE(3)\fP data. If you are using libcurl as a Windows DLL, this option causes an exception and a crash in the library since it cannot access a FILE * passed on from the application. A work\-around is to instead use \fICURLOPT_DEBUGFUNCTION(3)\fP. .SH DEFAULT stderr .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); FILE filep = fopen("dump", "wb"); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_STDERR, filep); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_NOPROGRESS (3), .BR CURLOPT_VERBOSE (3)	1.33 KB	2025-07-08 09:41
📄 CURLOPT_STREAM_DEPENDS.3 .\" generated by cd2nroff 0.1 from CURLOPT_STREAM_DEPENDS.md .TH CURLOPT_STREAM_DEPENDS 3 "2025-06-27" libcurl .SH NAME CURLOPT_STREAM_DEPENDS \- stream this transfer depends on .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_STREAM_DEPENDS, CURL dephandle); .fi .SH DESCRIPTION Pass a CURL pointer in \fIdephandle\fP to identify the stream within the same connection that this stream is depending upon. This option clears the exclusive bit and is mutually exclusive to the \fICURLOPT_STREAM_DEPENDS_E(3)\fP option. The spec says "Including a dependency expresses a preference to allocate resources to the identified stream rather than to the dependent stream." This option can be set during transfer. \fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function return an error. It must be another easy handle, and it also needs to be a handle of a transfer that is about to be sent over the same HTTP/2 connection for this option to have an actual effect. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); CURL curl2 = curl_easy_init(); /* a second handle / if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); / the second depends on the first / curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS, curl); / then add both to a multi handle and transfer them */ } } .fi .SH AVAILABILITY Added in curl 7.46.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_STREAM_DEPENDS_E (3), .BR CURLOPT_STREAM_WEIGHT (3)	1.88 KB	2025-07-08 09:41
📄 CURLOPT_STREAM_DEPENDS_E.3 .\" generated by cd2nroff 0.1 from CURLOPT_STREAM_DEPENDS_E.md .TH CURLOPT_STREAM_DEPENDS_E 3 "2025-06-27" libcurl .SH NAME CURLOPT_STREAM_DEPENDS_E \- stream this transfer depends on exclusively .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_STREAM_DEPENDS_E, CURL dephandle); .fi .SH DESCRIPTION Pass a \fICURL\fP pointer in \fIdephandle\fP to identify the stream within the same connection that this stream is depending upon exclusively. That means it depends on it and sets the Exclusive bit. The spec says "Including a dependency expresses a preference to allocate resources to the identified stream rather than to the dependent stream." Setting a dependency with the exclusive flag for a reprioritized stream causes all the dependencies of the new parent stream to become dependent on the reprioritized stream. This option can be set during transfer. \fIdephandle\fP must not be the same as \fIhandle\fP, that makes this function return an error. It must be another easy handle, and it also needs to be a handle of a transfer that is about to be sent over the same HTTP/2 connection for this option to have an actual effect. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); CURL curl2 = curl_easy_init(); /* a second handle / if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); / the second depends on the first / curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); curl_easy_setopt(curl2, CURLOPT_STREAM_DEPENDS_E, curl); / then add both to a multi handle and transfer them */ } } .fi .SH AVAILABILITY Added in curl 7.46.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLOPT_HTTP_VERSION (3), .BR CURLOPT_STREAM_DEPENDS (3), .BR CURLOPT_STREAM_WEIGHT (3)	2.04 KB	2025-07-08 09:41
📄 CURLOPT_STREAM_WEIGHT.3 .\" generated by cd2nroff 0.1 from CURLOPT_STREAM_WEIGHT.md .TH CURLOPT_STREAM_WEIGHT 3 "2025-06-27" libcurl .SH NAME CURLOPT_STREAM_WEIGHT \- numerical stream weight .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_STREAM_WEIGHT, long weight); .fi .SH DESCRIPTION Set the long \fIweight\fP to a number between 1 and 256. When using HTTP/2, this option sets the individual weight for this particular stream used by the easy \fIhandle\fP. Setting and using weights only makes sense and is only usable when doing multiple streams over the same connections, which thus implies that you use \fICURLMOPT_PIPELINING(3)\fP. This option can be set during transfer and causes the updated weight info get sent to the server the next time an HTTP/2 frame is sent to the server. See section 5.3 of RFC 7540 for protocol details. Streams with the same parent should be allocated resources proportionally based on their weight. If you have two streams going, stream A with weight 16 and stream B with weight 32, stream B gets two thirds (32/48) of the available bandwidth (assuming the server can send off the data equally for both streams). .SH DEFAULT 16 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); CURL curl2 = curl_easy_init(); / a second handle / if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/one"); curl_easy_setopt(curl, CURLOPT_STREAM_WEIGHT, 10L); / the second has twice the weight / curl_easy_setopt(curl2, CURLOPT_URL, "https://example.com/two"); curl_easy_setopt(curl2, CURLOPT_STREAM_WEIGHT, 20L); / then add both to a multi handle and transfer them */ } } .fi .SH AVAILABILITY Added in curl 7.46.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLMOPT_PIPELINING (3), .BR CURLOPT_PIPEWAIT (3), .BR CURLOPT_STREAM_DEPENDS (3), .BR CURLOPT_STREAM_DEPENDS_E (3)	2.05 KB	2025-07-08 09:41
📄 CURLOPT_SUPPRESS_CONNECT_HEADERS.3 .\" generated by cd2nroff 0.1 from CURLOPT_SUPPRESS_CONNECT_HEADERS.md .TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "2025-06-27" libcurl .SH NAME CURLOPT_SUPPRESS_CONNECT_HEADERS \- suppress proxy CONNECT response headers .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_SUPPRESS_CONNECT_HEADERS, long onoff); .fi .SH DESCRIPTION When \fICURLOPT_HTTPPROXYTUNNEL(3)\fP is used and a CONNECT request is made, suppress proxy CONNECT response headers from the user callback functions \fICURLOPT_HEADERFUNCTION(3)\fP and \fICURLOPT_WRITEFUNCTION(3)\fP. Proxy CONNECT response headers can complicate header processing since it is essentially a separate set of headers. You can enable this option to suppress those headers. For example let\(aqs assume an HTTPS URL is to be retrieved via CONNECT. On success there would normally be two sets of headers, and each header line sent to the header function and/or the write function. The data given to the callbacks would look like this: .nf HTTP/1.1 200 Connection established {headers} \&... HTTP/1.1 200 OK Content-Type: application/json {headers} \&... {body} \&... .fi However by enabling this option the CONNECT response headers are suppressed, so the data given to the callbacks would look like this: .nf HTTP/1.1 200 OK Content-Type: application/json {headers} \&... {body} \&... .fi .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_HEADER, 1L); curl_easy_setopt(curl, CURLOPT_PROXY, "http://foo:3128"); curl_easy_setopt(curl, CURLOPT_HTTPPROXYTUNNEL, 1L); curl_easy_setopt(curl, CURLOPT_SUPPRESS_CONNECT_HEADERS, 1L); curl_easy_perform(curl); /* always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.54.0 .SH RETURN VALUE CURLE_OK or an error such as CURLE_UNKNOWN_OPTION. .SH SEE ALSO .BR CURLOPT_HEADER (3), .BR CURLOPT_HTTPPROXYTUNNEL (3), .BR CURLOPT_PROXY (3)	2.07 KB	2025-07-08 09:41
📄 CURLOPT_TCP_FASTOPEN.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_FASTOPEN.md .TH CURLOPT_TCP_FASTOPEN 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_FASTOPEN \- TCP Fast Open .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_FASTOPEN, long enable); .fi .SH DESCRIPTION Pass a long as parameter set to 1L to enable or 0 to disable. TCP Fast Open (RFC 7413) is a mechanism that allows data to be carried in the SYN and SYN\-ACK packets and consumed by the receiving end during the initial connection handshake, saving up to one full round\-trip time (RTT). Beware: the TLS session cache does not work when TCP Fast Open is enabled. TCP Fast Open is also known to be problematic on or across certain networks. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L); curl_easy_perform(curl); } } .fi .SH NOTES This option is only supported on Linux and macOS 10.11 or later. .SH AVAILABILITY Added in curl 7.49.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_SSL_FALSESTART (3)	1.35 KB	2025-07-08 09:41
📄 CURLOPT_TCP_KEEPALIVE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPALIVE.md .TH CURLOPT_TCP_KEEPALIVE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_KEEPALIVE \- TCP keep\-alive probing .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_KEEPALIVE, long probe); .fi .SH DESCRIPTION Pass a long. If set to 1, TCP keepalive probes are used. The delay and frequency of these probes can be controlled by the \fICURLOPT_TCP_KEEPIDLE(3)\fP, \fICURLOPT_TCP_KEEPINTVL(3)\fP, and \fICURLOPT_TCP_KEEPCNT(3)\fP options, provided the operating system supports them. Set to 0 (default behavior) to disable keepalive probes. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable TCP keep-alive for this transfer / curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); / keep-alive idle time to 120 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); / interval time between keep-alive probes: 60 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); / maximum number of keep-alive probes: 3 */ curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.25.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_MAX_RECV_SPEED_LARGE (3), .BR CURLOPT_TCP_KEEPCNT (3), .BR CURLOPT_TCP_KEEPIDLE (3), .BR CURLOPT_TCP_KEEPINTVL (3)	1.68 KB	2025-07-08 09:41
📄 CURLOPT_TCP_KEEPCNT.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPCNT.md .TH CURLOPT_TCP_KEEPCNT 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_KEEPCNT \- Maximum number of TCP keep\-alive probes .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_KEEPCNT, long cnt); .fi .SH DESCRIPTION Pass a long. Sets the number of probes to send before dropping the connection. Not all operating systems support this option. (Added in 8.9.0) The maximum value this option accepts is INT_MAX or whatever your system allows. Any larger value is capped to this amount. .SH DEFAULT 9 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable TCP keep-alive for this transfer / curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); / set keep-alive idle time to 120 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); / interval time between keep-alive probes: 60 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); / maximum number of keep-alive probes: 3 */ curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 8.9.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TCP_KEEPIDLE (3), .BR CURLOPT_TCP_KEEPINTVL (3)	1.56 KB	2025-07-08 09:41
📄 CURLOPT_TCP_KEEPIDLE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPIDLE.md .TH CURLOPT_TCP_KEEPIDLE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_KEEPIDLE \- TCP keep\-alive idle time wait .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_KEEPIDLE, long delay); .fi .SH DESCRIPTION Pass a long. Sets the \fIdelay\fP, in seconds, to wait while the connection is idle before sending keepalive probes. Not all operating systems support this option. The maximum value this accepts is 2147483648. Any larger value is capped to this amount. .SH DEFAULT 60 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable TCP keep-alive for this transfer / curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); / set keep-alive idle time to 120 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); / interval time between keep-alive probes: 60 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); / maximum number of keep-alive probes: 3 */ curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.25.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TCP_KEEPCNT (3), .BR CURLOPT_TCP_KEEPINTVL (3)	1.54 KB	2025-07-08 09:41
📄 CURLOPT_TCP_KEEPINTVL.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_KEEPINTVL.md .TH CURLOPT_TCP_KEEPINTVL 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_KEEPINTVL \- TCP keep\-alive interval .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_KEEPINTVL, long interval); .fi .SH DESCRIPTION Pass a long. Sets the interval, in seconds, to wait between sending keepalive probes. Not all operating systems support this option. (Added in 7.25.0) The maximum value this accepts is 2147483648. Any larger value is capped to this amount. .SH DEFAULT 60 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* enable TCP keep-alive for this transfer / curl_easy_setopt(curl, CURLOPT_TCP_KEEPALIVE, 1L); / set keep-alive idle time to 120 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPIDLE, 120L); / interval time between keep-alive probes: 60 seconds / curl_easy_setopt(curl, CURLOPT_TCP_KEEPINTVL, 60L); / maximum number of keep-alive probes: 3 */ curl_easy_setopt(curl, CURLOPT_TCP_KEEPCNT, 3L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.25.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TCP_KEEPCNT (3), .BR CURLOPT_TCP_KEEPIDLE (3)	1.53 KB	2025-07-08 09:41
📄 CURLOPT_TCP_NODELAY.3 .\" generated by cd2nroff 0.1 from CURLOPT_TCP_NODELAY.md .TH CURLOPT_TCP_NODELAY 3 "2025-06-27" libcurl .SH NAME CURLOPT_TCP_NODELAY \- the TCP_NODELAY option .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TCP_NODELAY, long nodelay); .fi .SH DESCRIPTION Pass a long specifying whether the \fITCP_NODELAY\fP option is to be set or cleared (1L = set, 0 = clear). The option is set by default. This has no effect after the connection has been established. Setting this option to 1L disables the Nagle algorithm on connections created using this handle. The purpose of this algorithm is to minimize the number of small packets on the network (where "small packets" means TCP segments less than the Maximum Segment Size for the network). Maximizing the amount of data sent per TCP segment is good because it amortizes the overhead of the send. However, in some cases small segments may need to be sent without delay. This is less efficient than sending larger amounts of data at a time, and can contribute to congestion on the network if overdone. .SH DEFAULT 1 .SH PROTOCOLS This functionality affects tcp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* leave Nagle enabled */ curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0L); curl_easy_perform(curl); } } .fi .SH HISTORY The default was changed to 1 from 0 in 7.50.2. .SH AVAILABILITY Added in curl 7.11.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_BUFFERSIZE (3), .BR CURLOPT_SOCKOPTFUNCTION (3), .BR CURLOPT_TCP_KEEPALIVE (3)	1.77 KB	2025-07-08 09:41
📄 CURLOPT_TELNETOPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_TELNETOPTIONS.md .TH CURLOPT_TELNETOPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_TELNETOPTIONS \- set of telnet options .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TELNETOPTIONS, struct curl_slist cmds); .fi .SH DESCRIPTION Provide a pointer to a curl_slist with variables to pass to the telnet negotiations. The variables should be in the format <option=value>. libcurl supports the options \fBTTYPE\fP, \fBXDISPLOC\fP and \fBNEW_ENV\fP. See the TELNET standard for details. Using this option multiple times makes the last set list override the previous ones. Set it to NULL to disable its use again. libcurl does not copy the list, it needs to be kept around until after the transfer has completed. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects telnet only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; struct curl_slist options; options = curl_slist_append(NULL, "TTTYPE=vt100"); options = curl_slist_append(options, "USER=foobar"); curl_easy_setopt(curl, CURLOPT_URL, "telnet://example.com/"); curl_easy_setopt(curl, CURLOPT_TELNETOPTIONS, options); res = curl_easy_perform(curl); curl_easy_cleanup(curl); curl_slist_free_all(options); } } .fi .SH AVAILABILITY Added in curl 7.7 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_QUOTE (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_TFTP_BLKSIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TFTP_BLKSIZE.md .TH CURLOPT_TFTP_BLKSIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TFTP_BLKSIZE \- TFTP block size .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TFTP_BLKSIZE, long blocksize); .fi .SH DESCRIPTION Specify \fIblocksize\fP to use for TFTP data transmission. Valid range as per RFC 2348 is 8\-65464 bytes. The default of 512 bytes is used if this option is not specified. The specified block size is only used if supported by the remote server. If the server does not return an option acknowledgment or returns an option acknowledgment with no block size, the default of 512 bytes is used. .SH DEFAULT 512 .SH PROTOCOLS This functionality affects tftp only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/bootimage"); /* try using larger blocks */ curl_easy_setopt(curl, CURLOPT_TFTP_BLKSIZE, 2048L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAXFILESIZE (3)	1.33 KB	2025-07-08 09:41
📄 CURLOPT_TFTP_NO_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_TFTP_NO_OPTIONS.md .TH CURLOPT_TFTP_NO_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_TFTP_NO_OPTIONS \- send no TFTP options requests .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TFTP_NO_OPTIONS, long onoff); .fi .SH DESCRIPTION Set \fIonoff\fP to 1L to exclude all TFTP options defined in RFC 2347, RFC 2348 and RFC 2349 from read and write requests. This option improves interoperability with legacy servers that do not acknowledge or properly implement TFTP options. When this option is used \fICURLOPT_TFTP_BLKSIZE(3)\fP is ignored. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects tftp only .SH EXAMPLE .nf size_t write_callback(char ptr, size_t size, size_t nmemb, void fp) { return fwrite(ptr, size, nmemb, (FILE )fp); } int main(void) { CURL curl = curl_easy_init(); if(curl) { FILE fp = fopen("foo.bin", "wb"); if(fp) { curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void )fp); curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, write_callback); curl_easy_setopt(curl, CURLOPT_URL, "tftp://example.com/foo.bin"); / do not send TFTP options requests / curl_easy_setopt(curl, CURLOPT_TFTP_NO_OPTIONS, 1L); / Perform the request */ curl_easy_perform(curl); fclose(fp); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.48.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TFTP_BLKSIZE (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_TIMECONDITION.3 .\" generated by cd2nroff 0.1 from CURLOPT_TIMECONDITION.md .TH CURLOPT_TIMECONDITION 3 "2025-06-27" libcurl .SH NAME CURLOPT_TIMECONDITION \- select condition for a time request .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TIMECONDITION, long cond); .fi .SH DESCRIPTION Pass a long as parameter. This defines how the \fICURLOPT_TIMEVALUE(3)\fP time value is treated. You can set this parameter to \fICURL_TIMECOND_IFMODSINCE\fP or \fICURL_TIMECOND_IFUNMODSINCE\fP. The last modification time of a file is not always known and in such instances this feature has no effect even if the given time condition would not have been met. \fIcurl_easy_getinfo(3)\fP with the \fICURLINFO_CONDITION_UNMET\fP option can be used after a transfer to learn if a zero\-byte successful \&"transfer" was due to this condition not matching. .SH DEFAULT CURL_TIMECOND_NONE (0) .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* January 1, 2020 is 1577833200 / curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); / If-Modified-Since the above time stamp / curl_easy_setopt(curl, CURLOPT_TIMECONDITION, (long)CURL_TIMECOND_IFMODSINCE); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_FILETIME (3), .BR CURLOPT_TIMEVALUE (3)	1.68 KB	2025-07-08 09:41
📄 CURLOPT_TIMEOUT.3 .\" generated by cd2nroff 0.1 from CURLOPT_TIMEOUT.md .TH CURLOPT_TIMEOUT 3 "2025-06-27" libcurl .SH NAME CURLOPT_TIMEOUT \- maximum time the transfer is allowed to complete .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TIMEOUT, long timeout); .fi .SH DESCRIPTION Pass a long as parameter containing \fItimeout\fP \- the maximum time in seconds that you allow the entire transfer operation to take. The whole thing, from start to end. Normally, name lookups can take a considerable time and limiting operations risk aborting perfectly normal operations. \fICURLOPT_TIMEOUT_MS(3)\fP is the same function but set in milliseconds. If both \fICURLOPT_TIMEOUT(3)\fP and \fICURLOPT_TIMEOUT_MS(3)\fP are set, the value set last is used. Since this option puts a hard limit on how long time a request is allowed to take, it has limited use in dynamic use cases with varying transfer times. That is especially apparent when using the multi interface, which may queue the transfer, and that time is included. You are advised to explore \fICURLOPT_LOW_SPEED_LIMIT(3)\fP, \fICURLOPT_LOW_SPEED_TIME(3)\fP or using \fICURLOPT_PROGRESSFUNCTION(3)\fP to implement your own timeout logic. The connection timeout set with \fICURLOPT_CONNECTTIMEOUT(3)\fP is included in this general all\-covering timeout. With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 3 and \fICURLOPT_TIMEOUT(3)\fP set to 5, the operation can never last longer than 5 seconds. With \fICURLOPT_CONNECTTIMEOUT(3)\fP set to 4 and \fICURLOPT_TIMEOUT(3)\fP set to 2, the operation can never last longer than 2 seconds. This option may cause libcurl to use the SIGALRM signal to timeout system calls on builds not using asynch DNS. In Unix\-like systems, this might cause signals to be used unless \fICURLOPT_NOSIGNAL(3)\fP is set. .SH DEFAULT 0 (zero) which means it never times out during transfer. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* complete within 20 seconds */ curl_easy_setopt(curl, CURLOPT_TIMEOUT, 20L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT (3), .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TIMEOUT_MS (3)	2.53 KB	2025-07-08 09:41
📄 CURLOPT_TIMEOUT_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_TIMEOUT_MS.md .TH CURLOPT_TIMEOUT_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_TIMEOUT_MS \- maximum time the transfer is allowed to complete .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TIMEOUT_MS, long timeout); .fi .SH DESCRIPTION Pass a long as parameter containing \fItimeout\fP \- the maximum time in milliseconds that you allow the libcurl transfer operation to take. See \fICURLOPT_TIMEOUT(3)\fP for details. .SH DEFAULT 0 (zero) which means it never times out during transfer. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* complete within 20000 milliseconds */ curl_easy_setopt(curl, CURLOPT_TIMEOUT_MS, 20000L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.16.2 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECTTIMEOUT (3), .BR CURLOPT_LOW_SPEED_LIMIT (3), .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TIMEOUT (3)	1.26 KB	2025-07-08 09:41
📄 CURLOPT_TIMEVALUE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TIMEVALUE.md .TH CURLOPT_TIMEVALUE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TIMEVALUE \- time value for conditional .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TIMEVALUE, long val); .fi .SH DESCRIPTION Pass a long \fIval\fP as parameter. This should be the time counted as seconds since 1 Jan 1970, and the time is used in a condition as specified with \fICURLOPT_TIMECONDITION(3)\fP. On systems with 32\-bit \(aqlong\(aq variables (such as Windows), this option cannot set dates beyond the year 2038. Consider \fICURLOPT_TIMEVALUE_LARGE(3)\fP instead. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* January 1, 2020 is 1577833200 / curl_easy_setopt(curl, CURLOPT_TIMEVALUE, 1577833200L); / If-Modified-Since the above time stamp / curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TIMECONDITION (3), .BR CURLOPT_TIMEVALUE_LARGE (3)	1.42 KB	2025-07-08 09:41
📄 CURLOPT_TIMEVALUE_LARGE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TIMEVALUE_LARGE.md .TH CURLOPT_TIMEVALUE_LARGE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TIMEVALUE_LARGE \- time value for conditional .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TIMEVALUE_LARGE, curl_off_t val); .fi .SH DESCRIPTION Pass a curl_off_t \fIval\fP as parameter. This should be the time counted as seconds since 1 Jan 1970, and the time is used in a condition as specified with \fICURLOPT_TIMECONDITION(3)\fP. The difference between this option and \fICURLOPT_TIMEVALUE(3)\fP is the type of the argument. On systems where \(aqlong\(aq is only 32 bits wide, this option has to be used to set dates beyond the year 2038. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* January 1, 2020 is 1577833200 / curl_easy_setopt(curl, CURLOPT_TIMEVALUE_LARGE, (curl_off_t)1577833200); / If-Modified-Since the above time stamp / curl_easy_setopt(curl, CURLOPT_TIMECONDITION, CURL_TIMECOND_IFMODSINCE); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.59.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_FILETIME (3), .BR CURLOPT_TIMECONDITION (3), .BR CURLOPT_TIMEVALUE (3)	1.56 KB	2025-07-08 09:41
📄 CURLOPT_TLS13_CIPHERS.3 .\" generated by cd2nroff 0.1 from CURLOPT_TLS13_CIPHERS.md .TH CURLOPT_TLS13_CIPHERS 3 "2025-06-27" libcurl .SH NAME CURLOPT_TLS13_CIPHERS \- ciphers suites to use for TLS 1.3 .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TLS13_CIPHERS, char list); .fi .SH DESCRIPTION Pass a char pointer, pointing to a null\-terminated string holding the list of cipher suites to use for the TLS 1.3 connection. The list must be syntactically correct, it consists of one or more cipher suite strings separated by colons. For setting TLS 1.2 (1.1, 1.0) ciphers see \fICURLOPT_SSL_CIPHER_LIST(3)\fP. A valid example of a cipher list is: .nf "TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256" .fi Find more details about cipher lists on this URL: https://curl.se/docs/ssl\-ciphers.html The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to internal default. .SH DEFAULT NULL, use internal built\-in .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: OpenSSL, mbedTLS, rustls and wolfSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_TLS13_CIPHERS, "TLS_CHACHA20_POLY1305_SHA256"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY OpenSSL support added in 7.61.0, available when built with OpenSSL >= 1.1.1. LibreSSL support added in 8.3.0, available when built with LibreSSL >= 3.4.1. wolfSSL support added in 8.10.0. mbedTLS support added in 8.10.0, available when built with mbedTLS >= 3.6.0. Rustls support added in 8.10.0. Before curl 8.10.0 with mbedTLS or wolfSSL, TLS 1.3 cipher suites were set by using the \fICURLOPT_SSL_CIPHER_LIST(3)\fP option. .SH AVAILABILITY Added in curl 7.61.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_PROXY_SSL_CIPHER_LIST (3), .BR CURLOPT_PROXY_TLS13_CIPHERS (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_CIPHER_LIST (3), .BR CURLOPT_USE_SSL (3)	2.44 KB	2025-07-08 09:41
📄 CURLOPT_TLSAUTH_PASSWORD.3 .\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_PASSWORD.md .TH CURLOPT_TLSAUTH_PASSWORD 3 "2025-06-27" libcurl .SH NAME CURLOPT_TLSAUTH_PASSWORD \- password to use for TLS authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TLSAUTH_PASSWORD, char pwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should point to the null\-terminated password to use for the TLS authentication method specified with the \fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_TLSAUTH_USERNAME(3)\fP option also be set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. This feature relies on TLS SRP which does not work with TLS 1.3. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_TLSAUTH_PASSWORD (3), .BR CURLOPT_TLSAUTH_TYPE (3), .BR CURLOPT_TLSAUTH_USERNAME (3)	1.79 KB	2025-07-08 09:41
📄 CURLOPT_TLSAUTH_TYPE.3 .\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_TYPE.md .TH CURLOPT_TLSAUTH_TYPE 3 "2025-06-27" libcurl .SH NAME CURLOPT_TLSAUTH_TYPE \- TLS authentication methods .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TLSAUTH_TYPE, char type); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. The string should be the method of the TLS authentication. Supported method is "SRP". Using this option multiple times makes the last set string override the previous ones. Set it to NULL to restore to internal default. The application does not have to keep the string around after setting this option. .IP SRP TLS\-SRP authentication. Secure Remote Password authentication for TLS is defined in RFC 5054 and provides mutual authentication if both sides have a shared secret. To use TLS\-SRP, you must also set the \fICURLOPT_TLSAUTH_USERNAME(3)\fP and \fICURLOPT_TLSAUTH_PASSWORD(3)\fP options. TLS SRP does not work with TLS 1.3. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TLSAUTH_PASSWORD (3), .BR CURLOPT_TLSAUTH_USERNAME (3)	1.88 KB	2025-07-08 09:41
📄 CURLOPT_TLSAUTH_USERNAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_TLSAUTH_USERNAME.md .TH CURLOPT_TLSAUTH_USERNAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_TLSAUTH_USERNAME \- username to use for TLS authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TLSAUTH_USERNAME, char user); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should point to the null\-terminated username to use for the TLS authentication method specified with the \fICURLOPT_TLSAUTH_TYPE(3)\fP option. Requires that the \fICURLOPT_TLSAUTH_PASSWORD(3)\fP option also be set. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. This feature relies on TLS SRP which does not work with TLS 1.3. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: GnuTLS and OpenSSL .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TLSAUTH_PASSWORD (3), .BR CURLOPT_TLSAUTH_TYPE (3)	1.75 KB	2025-07-08 09:41
📄 CURLOPT_TRAILERDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_TRAILERDATA.md .TH CURLOPT_TRAILERDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_TRAILERDATA \- pointer passed to trailing headers callback .SH SYNOPSIS .nf #include <curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TRAILERDATA, void userdata); .fi .SH DESCRIPTION Data pointer to be passed to the HTTP trailer callback function. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf struct MyData { void custom; }; int main(void) { CURL curl = curl_easy_init(); if(curl) { struct MyData data; curl_easy_setopt(curl, CURLOPT_TRAILERDATA, &data); } } .fi .SH AVAILABILITY Added in curl 7.64.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TRAILERFUNCTION (3), .BR CURLOPT_WRITEFUNCTION (3)	962 B	2025-07-08 09:41
📄 CURLOPT_TRAILERFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_TRAILERFUNCTION.md .TH CURLOPT_TRAILERFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_TRAILERFUNCTION \- callback for sending trailing headers .SH SYNOPSIS .nf #include <curl.h> int curl_trailer_callback(struct curl_slist ** list, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_TRAILERFUNCTION, curl_trailer_callback func); .fi .SH DESCRIPTION Pass a pointer to a callback function. This callback function is called once right before sending the final CR LF in an HTTP chunked transfer to fill a list of trailing headers to be sent before finishing the HTTP transfer. You can set the userdata argument with the \fICURLOPT_TRAILERDATA(3)\fP option. The trailing headers included in the linked list must not be CRLF\-terminated, because libcurl adds the appropriate line termination characters after each header item. If you use \fIcurl_slist_append(3)\fP to add trailing headers to the \fIcurl_slist\fP then libcurl duplicates the strings, and frees the \fIcurl_slist\fP once the trailers have been sent. If one of the trailing header fields is not formatted correctly it is ignored and an info message is emitted. The return value can either be \fBCURL_TRAILERFUNC_OK\fP or \fBCURL_TRAILERFUNC_ABORT\fP which would respectively instruct libcurl to either continue with sending the trailers or to abort the request. If you set this option to NULL, then the transfer proceeds as usual without any interruptions. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf extern size_t read_cb(char ptr, size_t size, size_t nmemb, void userdata); static int trailer_cb(struct curl_slist tr, void data) { /* libcurl frees the list / tr = curl_slist_append(tr, "My-super-awesome-trailer: trailer-stuff"); return CURL_TRAILERFUNC_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; /* Set the URL of the request / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); / Now set it as a put / curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); / Assuming we have a function that returns the data to be pushed Let that function be read_cb / curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); struct curl_slist headers = NULL; headers = curl_slist_append(headers, "Trailer: My-super-awesome-trailer"); res = curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); /* Set the trailers filling callback / curl_easy_setopt(curl, CURLOPT_TRAILERFUNCTION, trailer_cb); / Perform the transfer */ res = curl_easy_perform(curl); curl_easy_cleanup(curl); curl_slist_free_all(headers); } } .fi .SH AVAILABILITY Added in curl 7.64.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TRAILERDATA (3), .BR CURLOPT_WRITEFUNCTION (3)	2.99 KB	2025-07-08 09:41
📄 CURLOPT_TRANSFERTEXT.3 .\" generated by cd2nroff 0.1 from CURLOPT_TRANSFERTEXT.md .TH CURLOPT_TRANSFERTEXT 3 "2025-06-27" libcurl .SH NAME CURLOPT_TRANSFERTEXT \- request a text based transfer for FTP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TRANSFERTEXT, long text); .fi .SH DESCRIPTION A parameter set to 1 tells the library to use ASCII mode for FTP transfers, instead of the default binary transfer. For Win32 systems it does not set the stdout to binary mode. This option can be usable when transferring text data between systems with different views on certain characters, such as newlines or similar. libcurl does not do a complete ASCII conversion when doing ASCII transfers over FTP. This is a known limitation/flaw that nobody has rectified. libcurl simply sets the mode to ASCII and performs a standard transfer. .SH DEFAULT 0, disabled .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/textfile"); curl_easy_setopt(curl, CURLOPT_TRANSFERTEXT, 1L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CRLF (3)	1.47 KB	2025-07-08 09:41
📄 CURLOPT_TRANSFER_ENCODING.3 .\" generated by cd2nroff 0.1 from CURLOPT_TRANSFER_ENCODING.md .TH CURLOPT_TRANSFER_ENCODING 3 "2025-06-27" libcurl .SH NAME CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_TRANSFER_ENCODING, long enable); .fi .SH DESCRIPTION Pass a long set to 1L to \fIenable\fP or 0 to disable. Adds a request for compressed Transfer Encoding in the outgoing HTTP request. If the server supports this and so desires, it can respond with the HTTP response sent using a compressed Transfer\-Encoding that is automatically uncompressed by libcurl on reception. Transfer\-Encoding differs slightly from the Content\-Encoding you ask for with \fICURLOPT_ACCEPT_ENCODING(3)\fP in that a Transfer\-Encoding is strictly meant to be for the transfer and thus MUST be decoded before the data arrives in the client. Traditionally, Transfer\-Encoding has been much less used and supported by both HTTP clients and HTTP servers. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.21.6 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ACCEPT_ENCODING (3), .BR CURLOPT_HTTP_TRANSFER_DECODING (3)	1.62 KB	2025-07-08 09:41
📄 CURLOPT_UNIX_SOCKET_PATH.3 .\" generated by cd2nroff 0.1 from CURLOPT_UNIX_SOCKET_PATH.md .TH CURLOPT_UNIX_SOCKET_PATH 3 "2025-06-27" libcurl .SH NAME CURLOPT_UNIX_SOCKET_PATH \- Unix domain socket .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UNIX_SOCKET_PATH, char path); .fi .SH DESCRIPTION Enables the use of Unix domain sockets as connection endpoint and sets the path to \fIpath\fP. If \fIpath\fP is NULL, then Unix domain sockets are disabled. When enabled, curl connects to the Unix domain socket instead of establishing a TCP connection to the host. Since no network connection is created, curl does not resolve the DNS hostname in the URL. The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms it might be even less. Proxy and TCP options such as \fICURLOPT_TCP_NODELAY(3)\fP are not supported. Proxy options such as \fICURLOPT_PROXY(3)\fP have no effect either as these are TCP\-oriented, and asking a proxy server to connect to a certain Unix domain socket is not possible. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL \- no Unix domain sockets are used. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock"); curl_easy_setopt(curl, CURLOPT_URL, "http://localhost/"); curl_easy_perform(curl); } } .fi If you are on Linux and somehow have a need for paths larger than 107 bytes, you can use the \fIproc\fP filesystem to bypass the limitation: .nf int dirfd = open(long_directory_path_to_socket, O_DIRECTORY \| O_RDONLY); char path[108]; snprintf(path, sizeof(path), "/proc/self/fd/%d/httpd.sock", dirfd); curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); / Be sure to keep dirfd valid until you discard the handle */ .fi .SH AVAILABILITY Added in curl 7.40.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_ABSTRACT_UNIX_SOCKET (3), .BR CURLOPT_OPENSOCKETFUNCTION (3), .BR unix (7)	2.34 KB	2025-07-08 09:41
📄 CURLOPT_UNRESTRICTED_AUTH.3 .\" generated by cd2nroff 0.1 from CURLOPT_UNRESTRICTED_AUTH.md .TH CURLOPT_UNRESTRICTED_AUTH 3 "2025-06-27" libcurl .SH NAME CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UNRESTRICTED_AUTH, long goahead); .fi .SH DESCRIPTION Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send authentication (user+password) credentials or explicitly set cookie headers when following locations, even when the host changes. This option is meaningful only when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. Further, when this option is not used or set to \fB0L\fP, libcurl does not send custom nor internally generated \fIAuthentication:\fP or \fICookie:\fP headers on requests done to other hosts than the one used for the initial URL. Another host means that one or more of hostname, protocol scheme or port number changed. By default, libcurl only sends \fIAuthentication:\fP or explicitly set \fICookie:\fP headers to the initial host as given in the original URL, to avoid leaking username + password to other sites. This option should be used with caution: when curl follows redirects it blindly fetches the next URL as instructed by the server. Setting \fICURLOPT_UNRESTRICTED_AUTH(3)\fP to 1L makes curl trust the server and sends possibly sensitive credentials to any host the server points to, possibly again and again as the following hosts can keep redirecting to new hosts. Due to the way HTTP works, almost any header can be made to contain data a client may not want to pass on to other servers than the initially intended host and for all other headers than the two mentioned above, there is no protection from this happening when libcurl is told to follow redirects. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.10.4 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_REDIRECT_COUNT (3), .BR CURLOPT_FOLLOWLOCATION (3), .BR CURLOPT_MAXREDIRS (3), .BR CURLOPT_REDIR_PROTOCOLS_STR (3), .BR CURLOPT_USERPWD (3)	2.52 KB	2025-07-08 09:41
📄 CURLOPT_UPKEEP_INTERVAL_MS.3 .\" generated by cd2nroff 0.1 from CURLOPT_UPKEEP_INTERVAL_MS.md .TH CURLOPT_UPKEEP_INTERVAL_MS 3 "2025-06-27" libcurl .SH NAME CURLOPT_UPKEEP_INTERVAL_MS \- connection upkeep interval .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UPKEEP_INTERVAL_MS, long upkeep_interval_ms); .fi .SH DESCRIPTION Some protocols have "connection upkeep" mechanisms. These mechanisms usually send some traffic on existing connections in order to keep them alive; this can prevent connections from being closed due to overzealous firewalls, for example. The user needs to explicitly call \fIcurl_easy_upkeep(3)\fP in order to perform the upkeep work. Currently the only protocol with a connection upkeep mechanism is HTTP/2: when the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP is called, an HTTP/2 PING frame is sent on the connection. .SH DEFAULT CURL_UPKEEP_INTERVAL_DEFAULT (currently defined as 60000L, which is 60 seconds) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { /* Make a connection to an HTTP/2 server. / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Set the interval to 30000ms / 30s / curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); curl_easy_perform(curl); / Perform more work here. / / While the connection is being held open, curl_easy_upkeep() can be called. If curl_easy_upkeep() is called and the time since the last upkeep exceeds the interval, then an HTTP/2 PING is sent. / curl_easy_upkeep(curl); / Perform more work here. / / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_TCP_KEEPALIVE (3)	2.01 KB	2025-07-08 09:41
📄 CURLOPT_UPLOAD.3 .\" generated by cd2nroff 0.1 from CURLOPT_UPLOAD.md .TH CURLOPT_UPLOAD 3 "2025-06-27" libcurl .SH NAME CURLOPT_UPLOAD \- data upload .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UPLOAD, long upload); .fi .SH DESCRIPTION The long parameter \fIupload\fP set to 1 tells the library to prepare for and perform an upload. The \fICURLOPT_READDATA(3)\fP and \fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP options are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell libcurl otherwise. Using PUT with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. If you use PUT to an HTTP 1.1 server, you can upload data without knowing the size before starting the transfer. The library enables this by adding a header \&"Transfer\-Encoding: chunked". With HTTP 1.0 or if you prefer not to use chunked transfer, you must specify the size of the data with \fICURLOPT_INFILESIZE(3)\fP or \fICURLOPT_INFILESIZE_LARGE(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf static size_t read_cb(char ptr, size_t size, size_t nmemb, void userdata) { FILE src = userdata; /* copy as much data as possible into the 'ptr' buffer, but no more than 'size' * 'nmemb' bytes / size_t retcode = fread(ptr, size, nmemb, src); return retcode; } int main(void) { CURL curl = curl_easy_init(); if(curl) { FILE src = fopen("local-file", "r"); curl_off_t fsize = 1234; / set this to the size of the input file / / we want to use our own read function / curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); / enable uploading / curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); / specify target / curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/to/newfile"); / now specify which pointer to pass to our callback / curl_easy_setopt(curl, CURLOPT_READDATA, src); / Set the size of the file to upload / curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); / Now run off and do what you have been told */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_INFILESIZE_LARGE (3), .BR CURLOPT_PUT (3), .BR CURLOPT_READFUNCTION (3)	2.54 KB	2025-07-08 09:41
📄 CURLOPT_UPLOAD_BUFFERSIZE.3 .\" generated by cd2nroff 0.1 from CURLOPT_UPLOAD_BUFFERSIZE.md .TH CURLOPT_UPLOAD_BUFFERSIZE 3 "2025-06-27" libcurl .SH NAME CURLOPT_UPLOAD_BUFFERSIZE \- upload buffer size .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UPLOAD_BUFFERSIZE, long size); .fi .SH DESCRIPTION Pass a long specifying your preferred \fIsize\fP (in bytes) for the upload buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to the next layer in the stack to get sent off. In some setups and for some protocols, there is a huge performance benefit of having a larger upload buffer. This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size. The upload buffer size is by default 64 kilobytes. The maximum buffer size allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is 16 kilobytes. The upload buffer is allocated on\-demand \- so if the handle is not used for upload, this buffer is not allocated at all. DO NOT set this option on a handle that is currently used for an active transfer as that may lead to unintended consequences. .SH DEFAULT 65536 bytes .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/foo.bin"); /* ask libcurl to allocate a larger upload buffer */ curl_easy_setopt(curl, CURLOPT_UPLOAD_BUFFERSIZE, 120000L); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_BUFFERSIZE (3), .BR CURLOPT_READFUNCTION (3), .BR CURLOPT_TCP_NODELAY (3)	1.89 KB	2025-07-08 09:41
📄 CURLOPT_UPLOAD_FLAGS.3 .\" generated by cd2nroff 0.1 from CURLOPT_UPLOAD_FLAGS.md .TH CURLOPT_UPLOAD_FLAGS 3 "2025-06-27" libcurl .SH NAME CURLOPT_UPLOAD_FLAGS \- upload flags for IMAP .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_UPLOAD_FLAGS, long bitmask); .fi .SH DESCRIPTION Pass a long as parameter, which is set to a bitmask, to tell libcurl which flags to send the server relating to uploaded files. The current supported flags are \fBCURLULFLAG_ANSWERED\fP, which sets the \fBAnswered\fP flag for IMAP uploads, \fBCURLULFLAG_DELETED\fP, which sets the \fBDeleted\fP flag for IMAP uploads, \fBCURLULFLAG_DRAFT\fP, which sets the \fBDraft\fP flag for IMAP uploads, \fBCURLULFLAG_FLAGGED\fP, which sets the \fBFlagged\fP flag for IMAP uploads, and \fBCURLULFLAG_SEEN\fP, which sets the \fBSeen\fP flag for IMAP uploads. .SH DEFAULT A bitmask with only the \fBCURLULFLAG_SEEN\fP flag set. .SH PROTOCOLS This functionality affects imap and imaps .SH EXAMPLE .nf static size_t read_cb(char ptr, size_t size, size_t nmemb, void userdata) { FILE src = userdata; /* copy as much data as possible into the 'ptr' buffer, but no more than 'size' * 'nmemb' bytes / size_t retcode = fread(ptr, size, nmemb, src); return retcode; } int main(void) { CURL curl = curl_easy_init(); if(curl) { FILE src = fopen("local-file", "r"); curl_off_t fsize = 9876; / set this to the size of the input file / / we want to use our own read function / curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_cb); / enable uploading / curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L); / specify target / curl_easy_setopt(curl, CURLOPT_URL, "imap://example.com:993/mailbox"); / provide username / curl_easy_setopt(curl, CURLOPT_USERNAME, "user@example.com"); / provide password / curl_easy_setopt(curl, CURLOPT_PASSWORD, "password"); / specify that uploaded mail should be considered flagged / curl_easy_setopt(curl, CURLOPT_UPLOAD_FLAGS, CURLULFLAG_FLAGGED); / now specify which pointer to pass to our callback / curl_easy_setopt(curl, CURLOPT_READDATA, src); / Set the size of the file to upload / curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fsize); / perform the upload */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 8.13.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_UPLOAD (3)	2.55 KB	2025-07-08 09:41
📄 CURLOPT_URL.3 .\" generated by cd2nroff 0.1 from CURLOPT_URL.md .TH CURLOPT_URL 3 "2025-06-27" libcurl .SH NAME CURLOPT_URL \- URL for this transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_URL, char URL); .fi .SH DESCRIPTION Pass in a pointer to the \fIURL\fP to work with. The parameter should be a char * to a null\-terminated string which must be URL\-encoded in the following format: scheme://host:port/path For a greater explanation of the format please see RFC 3986. libcurl does not validate the syntax or use the URL until the transfer is started. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP might still return \fICURLE_OK\fP. If the given URL is missing a scheme name (such as "http://" or "ftp://" etc) then libcurl guesses based on the host. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that protocol gets used, otherwise HTTP is used. Since 7.45.0 guessing can be disabled by setting a default protocol, see \fICURLOPT_DEFAULT_PROTOCOL(3)\fP for details. Should the protocol, either as specified by the URL scheme or deduced by libcurl from the hostname, not be supported by libcurl then \fICURLE_UNSUPPORTED_PROTOCOL\fP is returned from either the \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you call them. Use \fIcurl_version_info(3)\fP for detailed information of which protocols are supported by the build of libcurl you are using. \fICURLOPT_PROTOCOLS_STR(3)\fP can be used to limit what protocols libcurl may use for this transfer, independent of what libcurl has been compiled to support. That may be useful if you accept the URL from an external source and want to limit the accessibility. The \fICURLOPT_URL(3)\fP string is ignored if \fICURLOPT_CURLU(3)\fP is set. Either \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP must be set before a transfer is started. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. Note however that libcurl needs a URL set to be able to performed a transfer. The parser used for handling the URL set with \fICURLOPT_URL(3)\fP is the same that \fIcurl_url_set(3)\fP uses. .SH ENCODING The string pointed to in the \fICURLOPT_URL(3)\fP argument is generally expected to be a sequence of characters using an ASCII compatible encoding. If libcurl is built with IDN support, the server name part of the URL can use an "international name" by using the current encoding (according to locale) or UTF\-8 (when WinIDN is used; or a Windows Unicode build using libidn2). If libcurl is built without IDN support, the server name is used exactly as specified when passed to the name resolver functions. .SH DEFAULT NULL. If this option is not set, no transfer can be performed. .SH SECURITY CONCERNS Applications may at times find it convenient to allow users to specify URLs for various purposes and that string would then end up fed to this option. Getting a URL from an external untrusted party brings several security concerns: If you have an application that runs as or in a server application, getting an unfiltered URL can easily trick your application to access a local resource instead of a remote. Protecting yourself against localhost accesses is hard when accepting user provided URLs. Such custom URLs can also access other ports than you planned as port numbers are part of the regular URL format. The combination of a local host and a custom port number can allow external users to play tricks with your local services. Accepting external URLs may also use other protocols than http:// or other common ones. Restrict what accept with \fICURLOPT_PROTOCOLS_STR(3)\fP. User provided URLs can also be made to point to sites that redirect further on (possibly to other protocols too). Consider your \fICURLOPT_FOLLOWLOCATION(3)\fP and \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP settings. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. Note that \fIcurl_easy_setopt(3)\fP does not parse the given string so given a bad URL, it is not detected until \fIcurl_easy_perform(3)\fP or similar is called. .SH SEE ALSO .BR CURLINFO_REDIRECT_URL (3), .BR CURLOPT_CURLU (3), .BR CURLOPT_FORBID_REUSE (3), .BR CURLOPT_FRESH_CONNECT (3), .BR CURLOPT_PATH_AS_IS (3), .BR CURLOPT_PROTOCOLS_STR (3), .BR curl_easy_perform (3), .BR curl_url_get (3), .BR curl_url_set (3)	4.81 KB	2025-07-08 09:41
📄 CURLOPT_USERAGENT.3 .\" generated by cd2nroff 0.1 from CURLOPT_USERAGENT.md .TH CURLOPT_USERAGENT 3 "2025-06-27" libcurl .SH NAME CURLOPT_USERAGENT \- HTTP user\-agent header .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_USERAGENT, char ua); .fi .SH DESCRIPTION Pass a pointer to a null\-terminated string as parameter. It is used to set the User\-Agent: header field in the HTTP request sent to the remote server. You can also set any custom header with \fICURLOPT_HTTPHEADER(3)\fP. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL, no User\-Agent: header is used. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_setopt(curl, CURLOPT_USERAGENT, "Dark Secret Ninja/1.0"); curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CUSTOMREQUEST (3), .BR CURLOPT_HTTPHEADER (3), .BR CURLOPT_REFERER (3), .BR CURLOPT_REQUEST_TARGET (3)	1.4 KB	2025-07-08 09:41
📄 CURLOPT_USERNAME.3 .\" generated by cd2nroff 0.1 from CURLOPT_USERNAME.md .TH CURLOPT_USERNAME 3 "2025-06-27" libcurl .SH NAME CURLOPT_USERNAME \- username to use in authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_USERNAME, char username); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should be pointing to the null\-terminated username to use for the transfer. \fICURLOPT_USERNAME(3)\fP sets the username to be used in protocol authentication. You should not use this option together with the (older) \fICURLOPT_USERPWD(3)\fP option. When using Kerberos V5 authentication with a Windows based server, you should include the domain name in order for the server to successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. When using NTLM, the username can be specified simply as the username without the domain name should the server be part of a single domain and forest. To include the domain name use either Down\-Level Logon Name or UPN (User Principal Name) formats. For example, \fBEXAMPLE\user\fP and \fBuser@example.com\fP respectively. Some HTTP servers (on Windows) support inclusion of the domain for Basic authentication as well. To specify the password and login options, along with the username, use the \fICURLOPT_PASSWORD(3)\fP and \fICURLOPT_LOGIN_OPTIONS(3)\fP options. The application does not have to keep the string around after setting this option. .SH DEFAULT blank .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_USERNAME, "clark"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.19.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_HTTPAUTH (3), .BR CURLOPT_PASSWORD (3), .BR CURLOPT_PROXYAUTH (3), .BR CURLOPT_USERPWD (3)	2.2 KB	2025-07-08 09:41
📄 CURLOPT_USERPWD.3 .\" generated by cd2nroff 0.1 from CURLOPT_USERPWD.md .TH CURLOPT_USERPWD 3 "2025-06-27" libcurl .SH NAME CURLOPT_USERPWD \- username and password to use in authentication .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_USERPWD, char userpwd); .fi .SH DESCRIPTION Pass a char pointer as parameter, pointing to a null\-terminated login details string for the connection. The format of which is: [username]:[password]. When using Kerberos V5 authentication with a Windows based server, you should specify the username part with the domain name in order for the server to successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. When using NTLM, the username can be specified simply as the username without the domain name should the server be part of a single domain and forest. To specify the domain name use either Down\-Level Logon Name or UPN (User Principal Name) formats. For example \fBEXAMPLE\user\fP and \fBuser@example.com\fP respectively. Some HTTP servers (on Windows) support inclusion of the domain for Basic authentication as well. When using HTTP and \fICURLOPT_FOLLOWLOCATION(3)\fP, libcurl might perform several requests to possibly different hosts. libcurl only sends this user and password information to hosts using the initial hostname (unless \fICURLOPT_UNRESTRICTED_AUTH(3)\fP is set), so if libcurl follows redirects to other hosts, it does not send the user and password to those. This is enforced to prevent accidental information leakage. Use \fICURLOPT_HTTPAUTH(3)\fP to specify the authentication method for HTTP based connections or \fICURLOPT_LOGIN_OPTIONS(3)\fP to control IMAP, POP3 and SMTP options. The user and password strings are not URL decoded, so there is no way to send in a username containing a colon using this option. Use \fICURLOPT_USERNAME(3)\fP for that, or include it in the URL. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PASSWORD (3), .BR CURLOPT_PROXYUSERPWD (3), .BR CURLOPT_USERNAME (3)	2.79 KB	2025-07-08 09:41
📄 CURLOPT_USE_SSL.3 .\" generated by cd2nroff 0.1 from CURLOPT_USE_SSL.md .TH CURLOPT_USE_SSL 3 "2025-06-27" libcurl .SH NAME CURLOPT_USE_SSL \- request using SSL / TLS for the transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_USE_SSL, long level); .fi .SH DESCRIPTION Pass a long using one of the values from below, to make libcurl use your desired \fIlevel\fP of SSL for the transfer. These are all protocols that start out plain text and get "upgraded" to SSL using the STARTTLS command. This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. .IP CURLUSESSL_NONE do not attempt to use SSL. .IP CURLUSESSL_TRY Try using SSL, proceed as normal otherwise. Note that server may close the connection if the negotiation does not succeed. .IP CURLUSESSL_CONTROL Require SSL for the control connection or fail with \fICURLE_USE_SSL_FAILED\fP. .IP CURLUSESSL_ALL Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. .SH DEFAULT CURLUSESSL_NONE .SH PROTOCOLS This functionality affects ftp, imap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "ftp://example.com/dir/file.ext"); /* require use of SSL for this, or fail / curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL); / Perform the request */ curl_easy_perform(curl); } } .fi .SH HISTORY This option was known as CURLOPT_FTP_SSL up to 7.16.4. Supported by LDAP since 7.81.0. Fully supported by the OpenLDAP backend only. .SH AVAILABILITY Added in curl 7.17.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_PROXY_SSLVERSION (3), .BR CURLOPT_SSLVERSION (3), .BR CURLOPT_SSL_OPTIONS (3)	1.85 KB	2025-07-08 09:41
📄 CURLOPT_VERBOSE.3 .\" generated by cd2nroff 0.1 from CURLOPT_VERBOSE.md .TH CURLOPT_VERBOSE 3 "2025-06-27" libcurl .SH NAME CURLOPT_VERBOSE \- verbose mode .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_VERBOSE, long onoff); .fi .SH DESCRIPTION Set the \fIonoff\fP parameter to 1 to make the library display a lot of verbose information about its operations on this \fIhandle\fP. Useful for libcurl and/or protocol debugging and understanding. The verbose information is sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. You hardly ever want this enabled in production use, you almost always want this used when you debug/report problems. To also get all the protocol data sent and received, consider using the \fICURLOPT_DEBUGFUNCTION(3)\fP. \fBWARNING\fP this may show sensitive contents from headers and data. .SH DEFAULT 0, meaning disabled. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* ask libcurl to show us the verbose output / curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); / Perform the request */ curl_easy_perform(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_ERRORBUFFER (3), .BR CURLOPT_STDERR (3), .BR curl_global_trace (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_WILDCARDMATCH.3 .\" generated by cd2nroff 0.1 from CURLOPT_WILDCARDMATCH.md .TH CURLOPT_WILDCARDMATCH 3 "2025-06-27" libcurl .SH NAME CURLOPT_WILDCARDMATCH \- directory wildcard transfers .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_WILDCARDMATCH, long onoff); .fi .SH DESCRIPTION Set \fIonoff\fP to 1 if you want to transfer multiple files according to a filename pattern. The pattern can be specified as part of the \fICURLOPT_URL(3)\fP option, using an \fBfnmatch\fP\-like pattern (Shell Pattern Matching) in the last part of URL (filename). By default, libcurl uses its internal wildcard matching implementation. You can provide your own matching function by the \fICURLOPT_FNMATCH_FUNCTION(3)\fP option. A brief introduction of its syntax follows: .IP " - ASTERISK" .nf ftp://example.com/some/path/.txt .fi matches all \fI.txt\fP files in the root directory. Only two asterisks are allowed within the same pattern string. .IP "? - QUESTION MARK" Question mark matches any (exactly one) character. .nf ftp://example.com/some/path/photo?.jpg .fi .IP "[ - BRACKET EXPRESSION" The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow: \fB[a\-zA\-Z0\-9]\fP or \fB[f\-gF\-G]\fP \- character interval \fB[abc]\fP \- character enumeration \fB[^abc]\fP or \fB[!abc]\fP \- negation \fB[[:name:]]\fP class expression. Supported classes are \fBalnum\fP,\fBlower\fP, \fBspace\fP, \fBalpha\fP, \fBdigit\fP, \fBprint\fP, \fBupper\fP, \fBblank\fP, \fBgraph\fP, \fBxdigit\fP. \fB[][\-!^]\fP \- special case \- matches only \(aq\-\(aq, \(aq]\(aq, \(aq[\(aq, \(aq!\(aq or \(aq^\(aq. These characters have no special purpose. \fB[[]]\fP \- escape syntax. Matches \(aq[\(aq, \(aq]\(aq or \(aqe\(aq. Using the rules above, a filename pattern can be constructed: .nf ftp://example.com/some/path/[a-z[:upper:]\\].jpg .fi .SH PROTOCOLS This functionality affects ftp only .SH EXAMPLE .nf extern long begin_cb(struct curl_fileinfo , void , int); extern long end_cb(void ptr); int main(void) { CURL curl = curl_easy_init(); if(curl) { / turn on wildcard matching / curl_easy_setopt(curl, CURLOPT_WILDCARDMATCH, 1L); / callback is called before download of concrete file started / curl_easy_setopt(curl, CURLOPT_CHUNK_BGN_FUNCTION, begin_cb); / callback is called after data from the file have been transferred / curl_easy_setopt(curl, CURLOPT_CHUNK_END_FUNCTION, end_cb); / See more on https://curl.se/libcurl/c/ftp-wildcard.html */ } } .fi .SH AVAILABILITY Added in curl 7.21.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CHUNK_BGN_FUNCTION (3), .BR CURLOPT_CHUNK_END_FUNCTION (3), .BR CURLOPT_FNMATCH_FUNCTION (3), .BR CURLOPT_URL (3)	2.98 KB	2025-07-08 09:41
📄 CURLOPT_WRITEDATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_WRITEDATA.md .TH CURLOPT_WRITEDATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_WRITEDATA \- pointer passed to the write callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_WRITEDATA, void pointer); .fi .SH DESCRIPTION A data \fIpointer\fP to pass to the write callback. If you use the \fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you get in that callback\(aqs fourth and last argument. If you do not use a write callback, you must make \fIpointer\fP a \(aqFILE \fI\(aq (cast to \(aqvoid \fP\(aq) as libcurl passes this to \fIfwrite(3)\fP when writing data. The internal \fICURLOPT_WRITEFUNCTION(3)\fP writes the data to the FILE * given with this option, or to stdout if this option has not been set. If you are using libcurl as a Windows DLL, you \fBMUST\fP use a \fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you might experience crashes. .SH DEFAULT stdout .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE A common technique is to use the write callback to store the incoming data into a dynamically growing allocated buffer, and then this \fICURLOPT_WRITEDATA(3)\fP is used to point to a struct or the buffer to store data in. Like in the \fIgetinmemory\fP example: https://curl.se/libcurl/c/getinmemory.html .SH HISTORY This option was formerly known as CURLOPT_FILE, the name \fICURLOPT_WRITEDATA(3)\fP was added in 7.9.7. .SH AVAILABILITY Added in curl 7.9.7 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HEADERDATA (3), .BR CURLOPT_READDATA (3), .BR CURLOPT_WRITEFUNCTION (3)	1.61 KB	2025-07-08 09:41
📄 CURLOPT_WRITEFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_WRITEFUNCTION.md .TH CURLOPT_WRITEFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_WRITEFUNCTION \- callback for writing received data .SH SYNOPSIS .nf #include <curl/curl.h> size_t write_callback(char ptr, size_t size, size_t nmemb, void userdata); CURLcode curl_easy_setopt(CURL handle, CURLOPT_WRITEFUNCTION, write_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This callback function gets called by libcurl as soon as there is data received that needs to be saved. For most transfers, this callback gets called many times and each invoke delivers another chunk of data. \fIptr\fP points to the delivered data, and the size of that data is \fInmemb\fP; \fIsize\fP is always 1. The data passed to this function is not null\-terminated. The callback function is passed as much data as possible in all invokes, but you must not make any assumptions. It may be one byte, it may be thousands. The maximum amount of body data that is passed to the write callback is defined in the curl.h header file: \fICURL_MAX_WRITE_SIZE\fP (the usual default is 16K). If \fICURLOPT_HEADER(3)\fP is enabled, which makes header data get passed to the write callback, you can get up to \fICURL_MAX_HTTP_HEADER\fP bytes of header data passed into it. This usually means 100K. This function may be called with zero bytes data if the transferred file is empty. Set the \fIuserdata\fP argument with the \fICURLOPT_WRITEDATA(3)\fP option. Your callback should return the number of bytes actually taken care of. If that amount differs from the amount passed to your callback function, it signals an error condition to the library. This causes the transfer to get aborted and the libcurl function used returns \fICURLE_WRITE_ERROR\fP. You can also abort the transfer by returning CURL_WRITEFUNC_ERROR (added in 7.87.0), which makes \fICURLE_WRITE_ERROR\fP get returned. If the callback function returns CURL_WRITEFUNC_PAUSE it pauses this transfer. See \fIcurl_easy_pause(3)\fP for further details. Set this option to NULL to get the internal default function used instead of your callback. The internal default function writes the data to the FILE given with \fICURLOPT_WRITEDATA(3)\fP. This option does not enable HSTS, you need to use \fICURLOPT_HSTS_CTRL(3)\fP to do that. .SH DEFAULT fwrite(3) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <stdlib.h> /* for realloc / #include <string.h> / for memcpy / struct memory { char response; size_t size; }; static size_t cb(char data, size_t size, size_t nmemb, void clientp) { size_t realsize = size * nmemb; struct memory mem = (struct memory )clientp; char ptr = realloc(mem->response, mem->size + realsize + 1); if(!ptr) return 0; / out of memory / mem->response = ptr; memcpy(&(mem->response[mem->size]), data, realsize); mem->size += realsize; mem->response[mem->size] = 0; return realsize; } int main(void) { struct memory chunk = {0}; CURLcode res; CURL curl = curl_easy_init(); if(curl) { /* send all data to this function / curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, cb); / we pass our 'chunk' struct to the callback function / curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void )&chunk); /* send a request / res = curl_easy_perform(curl); / remember to free the buffer */ free(chunk.response); curl_easy_cleanup(curl); } } .fi .SH HISTORY Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE This returns CURLE_OK. .SH SEE ALSO .BR CURLOPT_HEADERFUNCTION (3), .BR CURLOPT_READFUNCTION (3), .BR CURLOPT_WRITEDATA (3)	3.71 KB	2025-07-08 09:41
📄 CURLOPT_WS_OPTIONS.3 .\" generated by cd2nroff 0.1 from CURLOPT_WS_OPTIONS.md .TH CURLOPT_WS_OPTIONS 3 "2025-06-27" libcurl .SH NAME CURLOPT_WS_OPTIONS \- WebSocket behavior options .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_WS_OPTIONS, long bitmask); .fi .SH DESCRIPTION Pass a long with a bitmask to tell libcurl about specific WebSocket behaviors. To detach a WebSocket connection and use the \fIcurl_ws_send(3)\fP and \fIcurl_ws_recv(3)\fP functions after the HTTP upgrade procedure, set the \fICURLOPT_CONNECT_ONLY(3)\fP option to 2L. Available bits in the bitmask .IP "CURLWS_RAW_MODE (1)" Deliver "raw" WebSocket traffic to the \fICURLOPT_WRITEFUNCTION(3)\fP callback. In raw mode, libcurl does not handle pings or any other frame for the application. .IP "CURLWS_NOAUTOPONG (2)" Disable the automatic reply to PING messages. This means users must send a PONG message with \fIcurl_ws_send(3)\fP. This feature is added with version 8.14.0. .SH DEFAULT 0 .SH PROTOCOLS This functionality affects ws only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "ws://example.com/"); /* tell curl we deal with all the WebSocket magic ourselves */ curl_easy_setopt(curl, CURLOPT_WS_OPTIONS, (long)CURLWS_RAW_MODE); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.86.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_CONNECT_ONLY (3), .BR curl_ws_recv (3), .BR curl_ws_send (3)	1.69 KB	2025-07-08 09:41
📄 CURLOPT_XFERINFODATA.3 .\" generated by cd2nroff 0.1 from CURLOPT_XFERINFODATA.md .TH CURLOPT_XFERINFODATA 3 "2025-06-27" libcurl .SH NAME CURLOPT_XFERINFODATA \- pointer passed to the progress callback .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_XFERINFODATA, void pointer); .fi .SH DESCRIPTION Pass a \fIpointer\fP that is untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. This is an alias for \fICURLOPT_PROGRESSDATA(3)\fP. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct progress { char private; size_t size; }; static int progress_cb(void clientp, curl_off_t dltotal, curl_off_t dlnow, curl_off_t ultotal, curl_off_t ulnow) { struct progress memory = clientp; printf("private ptr: %p\\n", memory->private); / use the values / return 0; / all is good / } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct progress data; /* pass struct to callback */ curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, progress_cb); } } .fi .SH AVAILABILITY Added in curl 7.32.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NOPROGRESS (3), .BR CURLOPT_VERBOSE (3), .BR CURLOPT_XFERINFOFUNCTION (3)	1.58 KB	2025-07-08 09:41
📄 CURLOPT_XFERINFOFUNCTION.3 .\" generated by cd2nroff 0.1 from CURLOPT_XFERINFOFUNCTION.md .TH CURLOPT_XFERINFOFUNCTION 3 "2025-06-27" libcurl .SH NAME CURLOPT_XFERINFOFUNCTION \- progress meter callback .SH SYNOPSIS .nf #include <curl/curl.h> int progress_callback(void clientp, curl_off_t dltotal, curl_off_t dlnow, curl_off_t ultotal, curl_off_t ulnow); CURLcode curl_easy_setopt(CURL handle, CURLOPT_XFERINFOFUNCTION, progress_callback); .fi .SH DESCRIPTION Pass a pointer to your callback function, which should match the prototype shown above. This function gets called by libcurl instead of its internal equivalent with a frequent interval. While data is being transferred it gets called frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. \fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA(3)\fP, it is not used by libcurl but is only passed along from the application to the callback. The callback gets told how much data libcurl is about to transfer and has already transferred, in number of bytes. \fIdltotal\fP is the total number of bytes libcurl expects to download in this transfer. \fIdlnow\fP is the number of bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl expects to upload in this transfer. \fIulnow\fP is the number of bytes uploaded so far. Unknown/unused argument values passed to the callback are set to zero (like if you only download data, the upload size remains 0). Many times the callback is called one or more times first, before it knows the data sizes so a program must be made to handle that. Return zero from the callback if everything is fine. Return 1 from this callback to make libcurl abort the transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP. If your callback function returns CURL_PROGRESSFUNC_CONTINUE it makes libcurl to continue executing the default progress function. If you transfer data with the multi interface, this function is not called during periods of idleness unless you call the appropriate libcurl function that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. .SH DEFAULT NULL \- use the internal progress meter. That is rarely wanted by users. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct progress { char private; size_t size; }; static int xferinfo_callback(void clientp, curl_off_t dltotal, curl_off_t dlnow, curl_off_t ultotal, curl_off_t ulnow) { struct progress memory = clientp; printf("my ptr: %p\\n", memory->private); / use the values / return 0; / all is good / } int main(void) { CURL curl = curl_easy_init(); if(curl) { struct progress data; /* pass struct to callback / curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &data); / enable progress callback getting called */ curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L); curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, xferinfo_callback); } } .fi .SH AVAILABILITY Added in curl 7.32.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_NOPROGRESS (3), .BR CURLOPT_XFERINFODATA (3)	3.47 KB	2025-07-08 09:41
📄 CURLOPT_XOAUTH2_BEARER.3 .\" generated by cd2nroff 0.1 from CURLOPT_XOAUTH2_BEARER.md .TH CURLOPT_XOAUTH2_BEARER 3 "2025-06-27" libcurl .SH NAME CURLOPT_XOAUTH2_BEARER \- OAuth 2.0 access token .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLOPT_XOAUTH2_BEARER, char token); .fi .SH DESCRIPTION Pass a char pointer as parameter, which should point to the null\-terminated OAuth 2.0 Bearer Access Token for use with HTTP, IMAP, LDAP, POP3 and SMTP servers that support the OAuth 2.0 Authorization Framework. Note: For IMAP, LDAP, POP3 and SMTP, the username used to generate the Bearer Token should be supplied via the \fICURLOPT_USERNAME(3)\fP option. The application does not have to keep the string around after setting this option. Using this option multiple times makes the last set string override the previous ones. Set it to NULL to disable its use again. .SH DEFAULT NULL .SH PROTOCOLS This functionality affects http, imap, ldap, pop3 and smtp .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "pop3://example.com/"); curl_easy_setopt(curl, CURLOPT_XOAUTH2_BEARER, "1ab9cb22ba269a7"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH HISTORY Support for OpenLDAP added in 7.82.0. .SH AVAILABILITY Added in curl 7.33.0 .SH RETURN VALUE \fIcurl_easy_setopt(3)\fP returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLOPT_MAIL_AUTH (3), .BR CURLOPT_USERNAME (3)	1.58 KB	2025-07-08 09:41
📄 CURLSHOPT_LOCKFUNC.3 .\" generated by cd2nroff 0.1 from CURLSHOPT_LOCKFUNC.md .TH CURLSHOPT_LOCKFUNC 3 "2025-06-27" libcurl .SH NAME CURLSHOPT_LOCKFUNC \- mutex lock callback .SH SYNOPSIS .nf #include <curl/curl.h> void lockcb(CURL handle, curl_lock_data data, curl_lock_access access, void clientp); CURLSHcode curl_share_setopt(CURLSH share, CURLSHOPT_LOCKFUNC, lockcb); .fi .SH DESCRIPTION Set a mutex lock callback for the share object, to allow it to get used by multiple threads concurrently. There is a corresponding \fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again released. The \fIlockcb\fP argument must be a pointer to a function matching the prototype shown above. The arguments to the callback are: \fIhandle\fP is the currently active easy handle in use when the share object is intended to get used. The \fIdata\fP argument tells what kind of data libcurl wants to lock. Make sure that the callback uses a different lock for each kind of data. \fIaccess\fP defines what access type libcurl wants, shared or single. \fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. This pointer is not used by libcurl itself. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf extern void mutex_lock(CURL handle, curl_lock_data data, curl_lock_access access, void clientp); int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_LOCKFUNC, mutex_lock); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred. See \fIlibcurl\-errors(3)\fP for the full list with descriptions. .SH SEE ALSO .BR CURLSHOPT_UNLOCKFUNC (3), .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3)	1.87 KB	2025-07-08 09:41
📄 CURLSHOPT_SHARE.3 .\" generated by cd2nroff 0.1 from CURLSHOPT_SHARE.md .TH CURLSHOPT_SHARE 3 "2025-06-27" libcurl .SH NAME CURLSHOPT_SHARE \- add data to share .SH SYNOPSIS .nf #include <curl/curl.h> CURLSHcode curl_share_setopt(CURLSH share, CURLSHOPT_SHARE, long type); .fi .SH DESCRIPTION The \fItype\fP parameter specifies what specific data that should be shared and kept in the share object that was created with \fIcurl_share_init(3)\fP. The given \fItype\fP must be one of the values described below. You can set \fICURLSHOPT_SHARE(3)\fP multiple times with different data arguments to have the share object share multiple types of data. Unset a type again by setting \fICURLSHOPT_UNSHARE(3)\fP. .IP CURL_LOCK_DATA_COOKIE Cookie data is shared across the easy handles using this shared object. Note that this does not activate an easy handle\(aqs cookie handling. You can do that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. It is not supported to share cookies between multiple concurrent threads. .IP CURL_LOCK_DATA_DNS Cached DNS hosts are shared across the easy handles using this shared object. Note that when you use the multi interface, all easy handles added to the same multi handle share the DNS cache by default without using this option. .IP CURL_LOCK_DATA_SSL_SESSION SSL sessions are shared across the easy handles using this shared object. This reduces the time spent in the SSL handshake when reconnecting to the same server. This symbol was added in 7.10.3 but was not implemented until 7.23.0. Note that when you use the multi interface, all easy handles added to the same multi handle share the SSL session cache by default without using this option. .IP CURL_LOCK_DATA_CONNECT Put the connection cache in the share object and make all easy handles using this share object share the connection cache. It is not supported to share connections between multiple concurrent threads. Connections that are used for HTTP/2 or HTTP/3 multiplexing only get additional transfers added to them if the existing connection is held by the same multi or easy handle. libcurl does not support doing multiplexed streams in different threads using a shared connection. Support for \fBCURL_LOCK_DATA_CONNECT\fP was added in 7.57.0, but the symbol existed before this. Note that when you use the multi interface, all easy handles added to the same multi handle share the connection cache by default without using this option. .IP CURL_LOCK_DATA_PSL The Public Suffix List stored in the share object is made available to all easy handle bound to the later. Since the Public Suffix List is periodically refreshed, this avoids updates in too many different contexts. Added in 7.61.0. Note that when you use the multi interface, all easy handles added to the same multi handle share the PSL cache by default without using this option. .IP CURL_LOCK_DATA_HSTS The in\-memory HSTS cache. It is not supported to share the HSTS between multiple concurrent threads. Added in 7.88.0 .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_COOKIE); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred. See \fIlibcurl\-errors(3)\fP for the full list with descriptions. .SH SEE ALSO .BR CURLSHOPT_UNSHARE (3), .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3)	3.53 KB	2025-07-08 09:41
📄 CURLSHOPT_UNLOCKFUNC.3 .\" generated by cd2nroff 0.1 from CURLSHOPT_UNLOCKFUNC.md .TH CURLSHOPT_UNLOCKFUNC 3 "2025-06-27" libcurl .SH NAME CURLSHOPT_UNLOCKFUNC \- mutex unlock callback .SH SYNOPSIS .nf #include <curl/curl.h> void unlockcb(CURL handle, curl_lock_data data, void clientp); CURLSHcode curl_share_setopt(CURLSH share, CURLSHOPT_UNLOCKFUNC, unlockcb); .fi .SH DESCRIPTION Set a mutex unlock callback for the share object. There is a corresponding \fICURLSHOPT_LOCKFUNC(3)\fP callback called when the mutex is first locked. The \fIunlockcb\fP argument must be a pointer to a function matching the prototype shown above. The arguments to the callback are: \fIhandle\fP is the currently active easy handle in use when the share object is released. The \fIdata\fP argument tells what kind of data libcurl wants to unlock. Make sure that the callback uses a different lock for each kind of data. \fIclientp\fP is the private pointer you set with \fICURLSHOPT_USERDATA(3)\fP. This pointer is not used by libcurl itself. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf extern void mutex_unlock(CURL , curl_lock_data, void ); int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_UNLOCKFUNC, mutex_unlock); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred. See \fIlibcurl\-errors(3)\fP for the full list with descriptions. .SH SEE ALSO .BR CURLSHOPT_LOCKFUNC (3), .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3)	1.65 KB	2025-07-08 09:41
📄 CURLSHOPT_UNSHARE.3 .\" generated by cd2nroff 0.1 from CURLSHOPT_UNSHARE.md .TH CURLSHOPT_UNSHARE 3 "2025-06-27" libcurl .SH NAME CURLSHOPT_UNSHARE \- remove data to share .SH SYNOPSIS .nf #include <curl/curl.h> CURLSHcode curl_share_setopt(CURLSH share, CURLSHOPT_UNSHARE, long type); .fi .SH DESCRIPTION The \fItype\fP parameter specifies what specific data that should no longer be shared and kept in the share object that was created with \fIcurl_share_init(3)\fP. In other words, stop sharing that data in this shared object. The given \fItype\fP must be one of the values described below. You can set \fICURLSHOPT_UNSHARE(3)\fP multiple times with different data arguments to remove multiple types from the shared object. Add data to share again with \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_COOKIE Cookie data is no longer shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_DNS Cached DNS hosts are no longer shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_SSL_SESSION SSL session IDs are no longer shared across the easy handles using this shared object. .IP CURL_LOCK_DATA_CONNECT The connection cache is no longer shared. .IP CURL_LOCK_DATA_PSL The Public Suffix List is no longer shared. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_UNSHARE, CURL_LOCK_DATA_COOKIE); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred. See \fIlibcurl\-errors(3)\fP for the full list with descriptions. .SH SEE ALSO .BR CURLSHOPT_SHARE (3), .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3)	1.82 KB	2025-07-08 09:41
📄 CURLSHOPT_USERDATA.3 .\" generated by cd2nroff 0.1 from CURLSHOPT_USERDATA.md .TH CURLSHOPT_USERDATA 3 "2025-06-27" libcurl .SH NAME CURLSHOPT_USERDATA \- pointer passed to the lock and unlock mutex callbacks .SH SYNOPSIS .nf #include <curl/curl.h> CURLSHcode curl_share_setopt(CURLSH share, CURLSHOPT_USERDATA, void clientp); .fi .SH DESCRIPTION The \fIclientp\fP parameter is held verbatim by libcurl and is passed on as the \fIclientp\fP argument to the callbacks set with \fICURLSHOPT_LOCKFUNC(3)\fP and \fICURLSHOPT_UNLOCKFUNC(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf struct secrets { void custom; }; int main(void) { CURLSHcode sh; struct secrets private_stuff; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_USERDATA, &private_stuff); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10.3 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred. See \fIlibcurl\-errors(3)\fP for the full list with descriptions. .SH SEE ALSO .BR CURLSHOPT_LOCKFUNC (3), .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3)	1.18 KB	2025-07-08 09:41
📄 curl_easy_cleanup.3 .\" generated by cd2nroff 0.1 from curl_easy_cleanup.md .TH curl_easy_cleanup 3 "2025-06-27" libcurl .SH NAME curl_easy_cleanup \- free an easy handle .SH SYNOPSIS .nf #include <curl/curl.h> void curl_easy_cleanup(CURL handle); .fi .SH DESCRIPTION This function is the opposite of \fIcurl_easy_init(3)\fP. It closes down and frees all resources previously associated with this easy handle. This call closes all connections this handle has used and possibly has kept open until now unless the easy handle was attached to a multi handle while doing the transfers. Do not call this function if you intend to transfer more files, reusing handles is a key to good performance with libcurl. Occasionally you may get your progress callback or header callback called from within \fIcurl_easy_cleanup(3)\fP (if previously set for the handle using \fIcurl_easy_setopt(3)\fP). Like if libcurl decides to shut down the connection and the protocol is of a kind that requires a command/response sequence before disconnect. Examples of such protocols are FTP, POP3 and IMAP. Any use of the easy \fBhandle\fP after this function has been called and have returned, is illegal. To close an easy handle that has been used with the multi interface, make sure to first call \fIcurl_multi_remove_handle(3)\fP to remove it from the multi handle before it is closed. Passing in a NULL pointer in \fIhandle\fP makes this function return immediately with no action. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); if(res) printf("error: %s\\n", curl_easy_strerror(res)); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE None .SH SEE ALSO .BR curl_easy_duphandle (3), .BR curl_easy_init (3), .BR curl_easy_reset (3), .BR curl_multi_cleanup (3), .BR curl_multi_remove_handle (3)	1.98 KB	2025-07-08 09:41
📄 curl_easy_duphandle.3 .\" generated by cd2nroff 0.1 from curl_easy_duphandle.md .TH curl_easy_duphandle 3 "2025-06-27" libcurl .SH NAME curl_easy_duphandle \- clone an easy handle .SH SYNOPSIS .nf #include <curl/curl.h> CURL curl_easy_duphandle(CURL handle); .fi .SH DESCRIPTION This function returns a new curl handle, a duplicate, using all the options previously set in the input curl \fIhandle\fP. Both handles can subsequently be used independently and they must both be freed with \fIcurl_easy_cleanup(3)\fP. Any options that the input handle has been told to point to (as opposed to copy) with previous calls to \fIcurl_easy_setopt(3)\fP, are pointed to by the new handle as well. You must therefore make sure to keep the data around until both handles have been cleaned up. The new handle does \fBnot\fP inherit any state information, no connections, no SSL sessions and no cookies. It also does not inherit any share object states or options (created as if \fICURLOPT_SHARE(3)\fP was set to NULL). If the source handle has HSTS or alt\-svc enabled, the duplicate gets data read data from the main filename to populate the cache. In multi\-threaded programs, this function must be called in a synchronous way, the input handle may not be in use when cloned. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; CURL nother; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); nother = curl_easy_duphandle(curl); res = curl_easy_perform(nother); curl_easy_cleanup(nother); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.9 .SH RETURN VALUE If this function returns NULL, something went wrong and no valid handle was returned. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_init (3), .BR curl_easy_reset (3), .BR curl_global_init (3)	1.85 KB	2025-07-08 09:41
📄 curl_easy_escape.3 .\" generated by cd2nroff 0.1 from curl_easy_escape.md .TH curl_easy_escape 3 "2025-06-27" libcurl .SH NAME curl_easy_escape \- URL encode a string .SH SYNOPSIS .nf #include <curl/curl.h> char curl_easy_escape(CURL curl, const char string, int length); .fi .SH DESCRIPTION This function converts the given input \fIstring\fP to a URL encoded string and returns that as a new allocated string. All input characters that are not a\-z, A\-Z, 0\-9, \(aq\-\(aq, \(aq.\(aq, \(aq_\(aq or \(aq~\(aq are converted to their "URL escaped" version (\fB%NN\fP where \fBNN\fP is a two\-digit hexadecimal number). If \fIlength\fP is set to 0 (zero), \fIcurl_easy_escape(3)\fP uses strlen() on the input \fIstring\fP to find out the size. This function does not accept input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB). You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH ENCODING libcurl is typically not aware of, nor does it care about, character encodings. \fIcurl_easy_escape(3)\fP encodes the data byte\-by\-byte into the URL encoded version without knowledge or care for what particular character encoding the application or the receiving server may assume that the data uses. The caller of \fIcurl_easy_escape(3)\fP must make sure that the data passed in to the function is encoded correctly. .SH URLs URLs are by definition \fIURL encoded\fP. To create a proper URL from a set of components that may not be URL encoded already, you cannot just URL encode the entire URL string with \fIcurl_easy_escape(3)\fP, because it then also converts colons, slashes and other symbols that you probably want untouched. To create a proper URL from strings that are not already URL encoded, we recommend using libcurl\(aqs URL API: set the pieces with \fIcurl_url_set(3)\fP and get the final correct URL with \fIcurl_url_get(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { char *output = curl_easy_escape(curl, "data to convert", 15); if(output) { printf("Encoded: %s\\n", output); curl_free(output); } curl_easy_cleanup(curl); } } .fi .SH HISTORY Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was per\-handle character conversion support for some old operating systems such as TPF, but it was otherwise ignored. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE A pointer to a null\-terminated string or NULL if it failed. .SH SEE ALSO .BR curl_easy_unescape (3), .BR curl_url_get (3), .BR curl_url_set (3)	2.54 KB	2025-07-08 09:41
📄 curl_easy_getinfo.3 .\" generated by cd2nroff 0.1 from curl_easy_getinfo.md .TH curl_easy_getinfo 3 "2025-06-27" libcurl .SH NAME curl_easy_getinfo \- extract information from a curl handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_getinfo(CURL curl, CURLINFO info, ... ); .fi .SH DESCRIPTION Get the \fIinfo\fP kept in the \fIcurl\fP handle. The third argument \fBMUST\fP be pointing to the specific type of the used option which is documented in each man page of the \fIinfo\fP option. The data is stored accordingly and can be relied upon only if this function returns CURLE_OK. Use this function after a performed transfer if you want to get transfer related data. You should not free the memory returned by this function unless it is explicitly mentioned below. .SH OPTIONS The following information can be extracted: .IP CURLINFO_ACTIVESOCKET The session\(aqs active socket. See \fICURLINFO_ACTIVESOCKET(3)\fP .IP CURLINFO_APPCONNECT_TIME The time it took from the start until the SSL connect/handshake with the remote host was completed as a double in number of seconds. (Added in 7.19.0) .IP CURLINFO_APPCONNECT_TIME_T The time it took from the start until the SSL connect/handshake with the remote host was completed in number of microseconds. (Added in 7.60.0) See \fICURLINFO_APPCONNECT_TIME_T(3)\fP .IP CURLINFO_CAINFO Get the default value for \fICURLOPT_CAINFO(3)\fP. See \fICURLINFO_CAINFO(3)\fP .IP CURLINFO_CAPATH Get the default value for \fICURLOPT_CAPATH(3)\fP. See \fICURLINFO_CAPATH(3)\fP .IP CURLINFO_CERTINFO Certificate chain. See \fICURLINFO_CERTINFO(3)\fP .IP CURLINFO_CONDITION_UNMET Whether or not a time conditional was met or 304 HTTP response. See \fICURLINFO_CONDITION_UNMET(3)\fP .IP CURLINFO_CONNECT_TIME The time it took from the start until the connect to the remote host (or proxy) was completed. As a double. See \fICURLINFO_CONNECT_TIME(3)\fP .IP CURLINFO_CONNECT_TIME_T The time it took from the start until the connect to the remote host (or proxy) was completed. In microseconds. See \fICURLINFO_CONNECT_TIME_T(3)\fP. .IP CURLINFO_CONN_ID The ID of the last connection used by the transfer. (Added in 8.2.0) See \fICURLINFO_CONN_ID(3)\fP .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD (\fBDeprecated\fP) Content length from the Content\-Length header. See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD(3)\fP .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T Content length from the Content\-Length header. See \fICURLINFO_CONTENT_LENGTH_DOWNLOAD_T(3)\fP .IP CURLINFO_CONTENT_LENGTH_UPLOAD (\fBDeprecated\fP) Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD(3)\fP .IP CURLINFO_CONTENT_LENGTH_UPLOAD_T Upload size. See \fICURLINFO_CONTENT_LENGTH_UPLOAD_T(3)\fP .IP CURLINFO_CONTENT_TYPE Content type from the \fIContent\-Type:\fP header. We recommend using \fIcurl_easy_header(3)\fP instead. See \fICURLINFO_CONTENT_TYPE(3)\fP .IP CURLINFO_COOKIELIST List of all known cookies. See \fICURLINFO_COOKIELIST(3)\fP .IP CURLINFO_EARLYDATA_SENT_T Amount of TLS early data sent (in number of bytes) when CURLSSLOPT_EARLYDATA is enabled. .IP CURLINFO_EFFECTIVE_METHOD Last used HTTP method. See \fICURLINFO_EFFECTIVE_METHOD(3)\fP .IP CURLINFO_EFFECTIVE_URL Last used URL. See \fICURLINFO_EFFECTIVE_URL(3)\fP .IP CURLINFO_FILETIME Remote time of the retrieved document. See \fICURLINFO_FILETIME(3)\fP .IP CURLINFO_FILETIME_T Remote time of the retrieved document. See \fICURLINFO_FILETIME_T(3)\fP .IP CURLINFO_FTP_ENTRY_PATH The entry path after logging in to an FTP server. See \fICURLINFO_FTP_ENTRY_PATH(3)\fP .IP CURLINFO_HEADER_SIZE Number of bytes of all headers received. See \fICURLINFO_HEADER_SIZE(3)\fP .IP CURLINFO_HTTPAUTH_AVAIL Available HTTP authentication methods. See \fICURLINFO_HTTPAUTH_AVAIL(3)\fP .IP CURLINFO_HTTPAUTH_USED Used HTTP authentication method. See \fICURLINFO_HTTPAUTH_USED(3)\fP .IP CURLINFO_HTTP_CONNECTCODE Last proxy CONNECT response code. See \fICURLINFO_HTTP_CONNECTCODE(3)\fP .IP CURLINFO_HTTP_VERSION The http version used in the connection. See \fICURLINFO_HTTP_VERSION(3)\fP .IP CURLINFO_LASTSOCKET (\fBDeprecated\fP) Last socket used. See \fICURLINFO_LASTSOCKET(3)\fP .IP CURLINFO_LOCAL_IP Source IP address of the last connection. See \fICURLINFO_LOCAL_IP(3)\fP .IP CURLINFO_LOCAL_PORT Source port number of the last connection. See \fICURLINFO_LOCAL_PORT(3)\fP .IP CURLINFO_NAMELOOKUP_TIME Time from start until name resolving completed as a double. See \fICURLINFO_NAMELOOKUP_TIME(3)\fP .IP CURLINFO_NAMELOOKUP_TIME_T Time from start until name resolving completed in number of microseconds. See \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP .IP CURLINFO_NUM_CONNECTS Number of new successful connections used for previous transfer. See \fICURLINFO_NUM_CONNECTS(3)\fP .IP CURLINFO_OS_ERRNO The errno from the last failure to connect. See \fICURLINFO_OS_ERRNO(3)\fP .IP CURLINFO_POSTTRANSFER_TIME_T The time it took from the start until the last byte is sent by libcurl. In microseconds. (Added in 8.10.0) See \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP .IP CURLINFO_PRETRANSFER_TIME The time it took from the start until the file transfer is just about to begin. This includes all pre\-transfer commands and negotiations that are specific to the particular protocol(s) involved. See \fICURLINFO_PRETRANSFER_TIME(3)\fP .IP CURLINFO_PRETRANSFER_TIME_T The time it took from the start until the file transfer is just about to begin. This includes all pre\-transfer commands and negotiations that are specific to the particular protocol(s) involved. In microseconds. See \fICURLINFO_PRETRANSFER_TIME_T(3)\fP .IP CURLINFO_PRIMARY_IP Destination IP address of the last connection. See \fICURLINFO_PRIMARY_IP(3)\fP .IP CURLINFO_PRIMARY_PORT Destination port of the last connection. See \fICURLINFO_PRIMARY_PORT(3)\fP .IP CURLINFO_PRIVATE User\(aqs private data pointer. See \fICURLINFO_PRIVATE(3)\fP .IP CURLINFO_PROTOCOL (\fBDeprecated\fP) The protocol used for the connection. (Added in 7.52.0) See \fICURLINFO_PROTOCOL(3)\fP .IP CURLINFO_PROXYAUTH_AVAIL Available HTTP proxy authentication methods. See \fICURLINFO_PROXYAUTH_AVAIL(3)\fP .IP CURLINFO_PROXYAUTH_USED Used HTTP proxy authentication methods. See \fICURLINFO_PROXYAUTH_USED(3)\fP .IP CURLINFO_PROXY_ERROR Detailed proxy error. See \fICURLINFO_PROXY_ERROR(3)\fP .IP CURLINFO_PROXY_SSL_VERIFYRESULT Proxy certificate verification result. See \fICURLINFO_PROXY_SSL_VERIFYRESULT(3)\fP .IP CURLINFO_QUEUE_TIME_T The time during which the transfer was held in a waiting queue before it could start for real in number of microseconds. (Added in 8.6.0) See \fICURLINFO_QUEUE_TIME_T(3)\fP .IP CURLINFO_REDIRECT_COUNT Total number of redirects that were followed. See \fICURLINFO_REDIRECT_COUNT(3)\fP .IP CURLINFO_REDIRECT_TIME The time it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. So, this is zero if no redirection took place. As a double. See \fICURLINFO_REDIRECT_TIME(3)\fP .IP CURLINFO_REDIRECT_TIME_T The time it took for all redirection steps include name lookup, connect, pretransfer and transfer before final transaction was started. So, this is zero if no redirection took place. In number of microseconds. See \fICURLINFO_REDIRECT_TIME_T(3)\fP .IP CURLINFO_REDIRECT_URL URL a redirect would take you to, had you enabled redirects. See \fICURLINFO_REDIRECT_URL(3)\fP .IP CURLINFO_REFERER Referrer header. See \fICURLINFO_REFERER(3)\fP .IP CURLINFO_REQUEST_SIZE Number of bytes sent in the issued HTTP requests. See \fICURLINFO_REQUEST_SIZE(3)\fP .IP CURLINFO_RESPONSE_CODE Last received response code. See \fICURLINFO_RESPONSE_CODE(3)\fP .IP CURLINFO_RETRY_AFTER The value from the Retry\-After header. See \fICURLINFO_RETRY_AFTER(3)\fP .IP CURLINFO_RTSP_CLIENT_CSEQ The RTSP client CSeq that is expected next. See \fICURLINFO_RTSP_CLIENT_CSEQ(3)\fP .IP CURLINFO_RTSP_CSEQ_RECV RTSP CSeq last received. See \fICURLINFO_RTSP_CSEQ_RECV(3)\fP .IP CURLINFO_RTSP_SERVER_CSEQ The RTSP server CSeq that is expected next. See \fICURLINFO_RTSP_SERVER_CSEQ(3)\fP .IP CURLINFO_RTSP_SESSION_ID RTSP session ID. See \fICURLINFO_RTSP_SESSION_ID(3)\fP .IP CURLINFO_SCHEME The scheme used for the connection. (Added in 7.52.0) See \fICURLINFO_SCHEME(3)\fP .IP CURLINFO_SIZE_DOWNLOAD (\fBDeprecated\fP) Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD(3)\fP .IP CURLINFO_SIZE_DOWNLOAD_T Number of bytes downloaded. See \fICURLINFO_SIZE_DOWNLOAD_T(3)\fP .IP CURLINFO_SIZE_UPLOAD (\fBDeprecated\fP) Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD(3)\fP .IP CURLINFO_SIZE_UPLOAD_T Number of bytes uploaded. See \fICURLINFO_SIZE_UPLOAD_T(3)\fP .IP CURLINFO_SPEED_DOWNLOAD (\fBDeprecated\fP) Average download speed. See \fICURLINFO_SPEED_DOWNLOAD(3)\fP .IP CURLINFO_SPEED_DOWNLOAD_T Average download speed. See \fICURLINFO_SPEED_DOWNLOAD_T(3)\fP .IP CURLINFO_SPEED_UPLOAD (\fBDeprecated\fP) Average upload speed. See \fICURLINFO_SPEED_UPLOAD(3)\fP .IP CURLINFO_SPEED_UPLOAD_T Average upload speed in number of bytes per second. See \fICURLINFO_SPEED_UPLOAD_T(3)\fP .IP CURLINFO_SSL_ENGINES A list of OpenSSL crypto engines. See \fICURLINFO_SSL_ENGINES(3)\fP .IP CURLINFO_SSL_VERIFYRESULT Certificate verification result. See \fICURLINFO_SSL_VERIFYRESULT(3)\fP .IP CURLINFO_STARTTRANSFER_TIME The time it took from the start until the first byte is received by libcurl. As a double. See \fICURLINFO_STARTTRANSFER_TIME(3)\fP .IP CURLINFO_STARTTRANSFER_TIME_T The time it took from the start until the first byte is received by libcurl. In microseconds. See \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP .IP CURLINFO_TLS_SESSION (\fBDeprecated\fP) TLS session info that can be used for further processing. See \fICURLINFO_TLS_SESSION(3)\fP. Use \fICURLINFO_TLS_SSL_PTR(3)\fP instead. .IP CURLINFO_TLS_SSL_PTR TLS session info that can be used for further processing. See \fICURLINFO_TLS_SSL_PTR(3)\fP .IP CURLINFO_TOTAL_TIME Total time of previous transfer. See \fICURLINFO_TOTAL_TIME(3)\fP .IP CURLINFO_TOTAL_TIME_T Total time of previous transfer. See \fICURLINFO_TOTAL_TIME_T(3)\fP .IP CURLINFO_USED_PROXY Whether the proxy was used (Added in 8.7.0). See \fICURLINFO_USED_PROXY(3)\fP .IP CURLINFO_XFER_ID The ID of the transfer. (Added in 8.2.0) See \fICURLINFO_XFER_ID(3)\fP .SH TIMES An overview of the time values available from \fIcurl_easy_getinfo(3)\fP .nf curl_easy_perform() \| \|--QUEUE \|--\|--NAMELOOKUP \|--\|--\|--CONNECT \|--\|--\|--\|--APPCONNECT \|--\|--\|--\|--\|--PRETRANSFER \|--\|--\|--\|--\|--\|--POSTTRANSFER \|--\|--\|--\|--\|--\|--\|--STARTTRANSFER \|--\|--\|--\|--\|--\|--\|--\|--TOTAL \|--\|--\|--\|--\|--\|--\|--\|--REDIRECT .fi \fICURLINFO_QUEUE_TIME_T(3)\fP, \fICURLINFO_NAMELOOKUP_TIME_T(3)\fP, \fICURLINFO_CONNECT_TIME_T(3)\fP, \fICURLINFO_APPCONNECT_TIME_T(3)\fP, \fICURLINFO_PRETRANSFER_TIME_T(3)\fP, \fICURLINFO_POSTTRANSFER_TIME_T(3)\fP, \fICURLINFO_STARTTRANSFER_TIME_T(3)\fP, \fICURLINFO_TOTAL_TIME_T(3)\fP, \fICURLINFO_REDIRECT_TIME_T(3)\fP .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/"); res = curl_easy_perform(curl); if(CURLE_OK == res) { char ct; / ask for the content-type / res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct); if((CURLE_OK == res) && ct) printf("We received Content-Type: %s\\n", ct); } / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.4.1 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_easy_setopt (3)	11.65 KB	2025-07-08 09:41
📄 curl_easy_header.3 .\" generated by cd2nroff 0.1 from curl_easy_header.md .TH curl_easy_header 3 "2025-06-27" libcurl .SH NAME curl_easy_header \- get an HTTP header .SH SYNOPSIS .nf #include <curl/curl.h> CURLHcode curl_easy_header(CURL easy, const char name, size_t index, unsigned int origin, int request, struct curl_header *hout); .fi .SH DESCRIPTION \fIcurl_easy_header(3)\fP returns a pointer to a "curl_header" struct in \fBhout\fP with data for the HTTP response header \fIname\fP. The case insensitive null\-terminated header name should be specified without colon. \fIindex\fP 0 means asking for the first instance of the header. If the returned header struct has \fBamount\fP set larger than 1, it means there are more instances of the same header name available to get. Asking for a too big index makes \fBCURLHE_BADINDEX\fP get returned. The \fIorigin\fP argument is for specifying which headers to receive, as a single HTTP transfer might provide headers from several different places and they may then have different importance to the user and headers using the same name might be used. The \fIorigin\fP is a bitmask for what header sources you want. See the descriptions below. The \fIrequest\fP argument tells libcurl from which request you want headers from. A single transfer might consist of a series of HTTP requests and this argument lets you specify which particular individual request you want the headers from. 0 being the first request and then the number increases for further redirects or when multi\-state authentication is used. Passing in \-1 is a shortcut to "the last" request in the series, independently of the actual amount of requests used. libcurl stores and provides the actually used "correct" headers. If for example two headers with the same name arrive and the latter overrides the former, then only the latter is provided. If the first header survives the second, then only the first one is provided. An application using this API does not have to bother about multiple headers used wrongly. The memory for the returned struct is associated with the easy handle and subsequent calls to \fIcurl_easy_header(3)\fP clobber the struct used in the previous calls for the same easy handle. The application needs to copy the data if it wants to keep it around. The memory used for the struct gets freed with calling \fIcurl_easy_cleanup(3)\fP of the easy handle. The first line in an HTTP response is called the status line. It is not considered a header by this function. Headers are the "name: value" lines following the status. This function can be used before (all) headers have been received and is fine to call from within libcurl callbacks. It returns the state of the headers at the time it is called. .SH The header struct .nf struct curl_header { char name; char value; size_t amount; size_t index; unsigned int origin; void anchor; }; .fi The data \fBname\fP field points to, is the same as the requested name, but might have a different case. The data \fBvalue\fP field points to, comes exactly as delivered over the network but with leading and trailing whitespace and newlines stripped off. The \fIvalue\fP data is null\-terminated. For legacy HTTP/1 "folded headers", this API provides the full single value in an unfolded manner with a single whitespace between the lines. \fBamount\fP is how many headers using this name that exist, within the origin and request scope asked for. \fBindex\fP is the zero based entry number of this particular header, which in case this header was used more than once in the requested scope can be larger than 0 but is always less than \fBamount\fP. The \fBorigin\fP field in the "curl_header" struct has one of the origin bits set, indicating where from the header originates. At the time of this writing, there are 5 bits with defined use. The undocumented 27 remaining bits are reserved for future use and must not be assumed to have any particular value. \fBanchor\fP is a private handle used by libcurl internals. Do not modify. .SH ORIGINS .IP CURLH_HEADER The header arrived as a header from the server. .IP CURLH_TRAILER The header arrived as a trailer. A header that arrives after the body. .IP CURLH_CONNECT The header arrived in a CONNECT response. A CONNECT request is being done to setup a transfer "through" an HTTP(S) proxy. .IP CURLH_1XX The header arrived in an HTTP 1xx response. A 1xx response is an "intermediate" response that might happen before the "real" response. .IP CURLH_PSEUDO The header is an HTTP/2 or HTTP/3 pseudo header .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { struct curl_header type; CURL curl = curl_easy_init(); if(curl) { CURLHcode h; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); h = curl_easy_header(curl, "Content-Type", 0, CURLH_HEADER, -1, &type); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.83.0 .SH RETURN VALUE This function returns a CURLHcode indicating success or error. CURLHE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR CURLINFO_CONTENT_TYPE (3), .BR CURLOPT_HEADERFUNCTION (3), .BR curl_easy_nextheader (3), .BR curl_easy_perform (3), .BR libcurl-errors (3)	5.33 KB	2025-07-08 09:41
📄 curl_easy_init.3 .\" generated by cd2nroff 0.1 from curl_easy_init.md .TH curl_easy_init 3 "2025-06-27" libcurl .SH NAME curl_easy_init \- create an easy handle .SH SYNOPSIS .nf #include <curl/curl.h> CURL curl_easy_init(); .fi .SH DESCRIPTION This function allocates and returns an easy handle. Such a handle is used as input to other functions in the easy interface. This call must have a corresponding call to \fIcurl_easy_cleanup(3)\fP when the operation is complete. The easy handle is used to hold and control a single network transfer. It is encouraged to reuse easy handles for repeated transfers. An alternative way to get a new easy handle is to duplicate an already existing one with \fIcurl_easy_duphandle(3)\fP, which has the upside that it gets all the options that were set in the source handle set in the new copy as well. If you did not already call \fIcurl_global_init(3)\fP before calling this function, \fIcurl_easy_init(3)\fP does it automatically. This can be lethal in multi\-threaded cases for platforms where \fIcurl_global_init(3)\fP is not thread\-safe, and it may then result in resource problems because there is no corresponding cleanup. You are strongly advised to not allow this automatic behavior, by calling \fIcurl_global_init(3)\fP yourself properly. See the description in \fIlibcurl(3)\fP of global environment requirements for details of how to use this function. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_duphandle (3), .BR curl_easy_perform (3), .BR curl_easy_reset (3), .BR curl_global_init (3), .BR curl_multi_init (3)	1.96 KB	2025-07-08 09:41
📄 curl_easy_nextheader.3 .\" generated by cd2nroff 0.1 from curl_easy_nextheader.md .TH curl_easy_nextheader 3 "2025-06-27" libcurl .SH NAME curl_easy_nextheader \- get the next HTTP header .SH SYNOPSIS .nf #include <curl/curl.h> struct curl_header curl_easy_nextheader(CURL easy, unsigned int origin, int request, struct curl_header prev); .fi .SH DESCRIPTION This function lets an application iterate over all previously received HTTP headers. The \fIorigin\fP argument is for specifying which headers to receive, as a single HTTP transfer might provide headers from several different places and they may then have different importance to the user and headers using the same name might be used. The \fIorigin\fP is a bitmask for what header sources you want. See the \fIcurl_easy_header(3)\fP man page for the origin descriptions. The \fIrequest\fP argument tells libcurl from which request you want headers from. A single transfer might consist of a series of HTTP requests and this argument lets you specify which particular individual request you want the headers from. 0 being the first request and then the number increases for further redirects or when multi\-state authentication is used. Passing in \-1 is a shortcut to "the last" request in the series, independently of the actual amount of requests used. It is suggested that you pass in the same \fBorigin\fP and \fBrequest\fP when iterating over a range of headers as changing the value mid\-loop might give you unexpected results. If \fIprev\fP is NULL, this function returns a pointer to the first header stored within the given scope (origin + request). If \fIprev\fP is a pointer to a previously returned header struct, \fIcurl_easy_nextheader(3)\fP returns a pointer the next header stored within the given scope. This way, an application can iterate over all available headers. The memory for the struct this points to, is owned and managed by libcurl and is associated with the easy handle. Applications must copy the data if they want it to survive subsequent API calls or the life\-time of the easy handle. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { struct curl_header prev = NULL; struct curl_header h; CURL curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); curl_easy_perform(curl); /* extract the normal headers from the first request / while((h = curl_easy_nextheader(curl, CURLH_HEADER, 0, prev))) { printf("%s: %s\\n", h->name, h->value); prev = h; } / extract the normal headers + 1xx + trailers from the last request */ unsigned int origin = CURLH_HEADER\| CURLH_1XX \| CURLH_TRAILER; while((h = curl_easy_nextheader(curl, origin, -1, prev))) { printf("%s: %s\\n", h->name, h->value); prev = h; } } } .fi .SH AVAILABILITY Added in curl 7.83.0 .SH RETURN VALUE This function returns the next header, or NULL when there are no more (matching) headers or an error occurred. If this function returns NULL when \fIprev\fP was set to NULL, then there are no headers available within the scope to return. .SH SEE ALSO .BR curl_easy_header (3), .BR curl_easy_perform (3)	3.24 KB	2025-07-08 09:41
📄 curl_easy_option_by_id.3 .\" generated by cd2nroff 0.1 from curl_easy_option_by_id.md .TH curl_easy_option_by_id 3 "2025-06-27" libcurl .SH NAME curl_easy_option_by_id \- find an easy setopt option by id .SH SYNOPSIS .nf #include <curl/curl.h> const struct curl_easyoption curl_easy_option_by_id(CURLoption id); .fi .SH DESCRIPTION Given a \fICURLoption\fP \fBid\fP, this function returns a pointer to the \fIcurl_easyoption\fP struct, holding information about the \fIcurl_easy_setopt(3)\fP option using that id. The option id is the \fICURLOPT_\fP prefixed ones provided in the standard curl/curl.h header file. This function returns the non\-alias version of the cases where there is an alias function as well. If libcurl has no option with the given id, this function returns NULL. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { const struct curl_easyoption opt = curl_easy_option_by_id(CURLOPT_URL); if(opt) { printf("This option wants type %x\\n", opt->type); } } .fi .SH AVAILABILITY Added in curl 7.73.0 .SH RETURN VALUE A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. .SH SEE ALSO .BR curl_easy_option_by_name (3), .BR curl_easy_option_next (3), .BR curl_easy_setopt (3)	1.21 KB	2025-07-08 09:41
📄 curl_easy_option_by_name.3 .\" generated by cd2nroff 0.1 from curl_easy_option_by_name.md .TH curl_easy_option_by_name 3 "2025-06-27" libcurl .SH NAME curl_easy_option_by_name \- find an easy setopt option by name .SH SYNOPSIS .nf #include <curl/curl.h> const struct curl_easyoption curl_easy_option_by_name(const char name); .fi .SH DESCRIPTION Given a \fBname\fP, this function returns a pointer to the \fIcurl_easyoption\fP struct, holding information about the \fIcurl_easy_setopt(3)\fP option using that name. The name should be specified without the \fICURLOPT_\fP prefix and the name comparison is made case insensitive. If libcurl has no option with the given name, this function returns NULL. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { const struct curl_easyoption *opt = curl_easy_option_by_name("URL"); if(opt) { printf("This option wants CURLoption %x\\n", (int)opt->id); } } .fi .SH AVAILABILITY Added in curl 7.73.0 .SH RETURN VALUE A pointer to the \fIcurl_easyoption\fP struct for the option or NULL. .SH SEE ALSO .BR curl_easy_option_by_id (3), .BR curl_easy_option_next (3), .BR curl_easy_setopt (3)	1.13 KB	2025-07-08 09:41
📄 curl_easy_option_next.3 .\" generated by cd2nroff 0.1 from curl_easy_option_next.md .TH curl_easy_option_next 3 "2025-06-27" libcurl .SH NAME curl_easy_option_next \- iterate over easy setopt options .SH SYNOPSIS .nf #include <curl/curl.h> const struct curl_easyoption * curl_easy_option_next(const struct curl_easyoption prev); .fi .SH DESCRIPTION This function returns a pointer to the first or the next \fIcurl_easyoption\fP struct, providing an ability to iterate over all known options for \fIcurl_easy_setopt(3)\fP in this instance of libcurl. Pass a \fBNULL\fP argument as \fBprev\fP to get the first option returned, or pass in the current option to get the next one returned. If there is no more option to return, \fIcurl_easy_option_next(3)\fP returns NULL. The options returned by this functions are the ones known to this libcurl and information about what argument type they want. If the \fBCURLOT_FLAG_ALIAS\fP bit is set in the flags field, it means the name is provided for backwards compatibility as an alias. .SH struct .nf typedef enum { CURLOT_LONG, / long (a range of values) / CURLOT_VALUES, / (a defined set or bitmask) / CURLOT_OFF_T, / curl_off_t (a range of values) / CURLOT_OBJECT, / pointer (void ) / CURLOT_STRING, /* (char * to null-terminated buffer) / CURLOT_SLIST, / (struct curl_slist ) / CURLOT_CBPTR, /* (void * passed as-is to a callback) / CURLOT_BLOB, / blob (struct curl_blob ) / CURLOT_FUNCTION /* function pointer / } curl_easytype; / The CURLOPTTYPE_* id ranges can still be used to figure out what type/size to use for curl_easy_setopt() for the given id / struct curl_easyoption { const char name; CURLoption id; curl_easytype type; unsigned int flags; }; .fi .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { /* iterate over all available options / const struct curl_easyoption opt; opt = curl_easy_option_next(NULL); while(opt) { printf("Name: %s\\n", opt->name); opt = curl_easy_option_next(opt); } } .fi .SH AVAILABILITY Added in curl 7.73.0 .SH RETURN VALUE A pointer to the \fIcurl_easyoption\fP struct for the next option or NULL if no more options. .SH SEE ALSO .BR curl_easy_option_by_id (3), .BR curl_easy_option_by_name (3), .BR curl_easy_setopt (3)	2.29 KB	2025-07-08 09:41
📄 curl_easy_pause.3 .\" generated by cd2nroff 0.1 from curl_easy_pause.md .TH curl_easy_pause 3 "2025-06-27" libcurl .SH NAME curl_easy_pause \- pause and unpause a connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_pause(CURL handle, int bitmask ); .fi .SH DESCRIPTION Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused. Unlike most other libcurl functions, \fIcurl_easy_pause(3)\fP can be used from within callbacks. A connection can be paused by using this function or by letting the read or the write callbacks return the proper magic return code (\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback that returns pause signals to the library that it could not take care of any data at all, and that data is then delivered again to the callback when the transfer is unpaused. While it may feel tempting, take care and notice that you cannot call this function from another thread. To unpause, you may for example call it from the progress callback (\fICURLOPT_PROGRESSFUNCTION(3)\fP). When this function is called to unpause receiving, the write callback might get called before this function returns to deliver cached content. When libcurl delivers such cached data to the write callback, it is delivered as fast as possible, which may overstep the boundary set in \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP etc. The \fBhandle\fP argument identifies the transfer you want to pause or unpause. A paused transfer is excluded from low speed cancels via the \fICURLOPT_LOW_SPEED_LIMIT(3)\fP option and unpausing a transfer resets the time period required for the low speed limit to be met. The \fBbitmask\fP argument is a set of bits that sets the new state of the connection. The following bits can be used: .IP CURLPAUSE_RECV Pause receiving data. There is no data received on this connection until this function is called again without this bit set. Thus, the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is not called. .IP CURLPAUSE_SEND Pause sending data. There is no data sent on this connection until this function is called again without this bit set. Thus, the read callback (\fICURLOPT_READFUNCTION(3)\fP) is not called. .IP CURLPAUSE_ALL Convenience define that pauses both directions. .IP CURLPAUSE_CONT Convenience define that unpauses both directions. .SH LIMITATIONS The pausing of transfers does not work with protocols that work without network connectivity, like FILE://. Trying to pause such a transfer, in any direction, might cause problems or error. .SH MULTIPLEXED When a connection is used multiplexed, like for HTTP/2, and one of the transfers over the connection is paused and the others continue flowing, libcurl might end up buffering contents for the paused transfer. It has to do this because it needs to drain the socket for the other transfers and the already announced window size for the paused transfer allows the server to continue sending data up to that window size amount. By default, libcurl announces a 32 megabyte window size, which thus can make libcurl end up buffering 32 megabyte of data for a paused stream. When such a paused stream is unpaused again, any buffered data is delivered first. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { /* pause a transfer in both directions */ curl_easy_pause(curl, CURLPAUSE_RECV \| CURLPAUSE_SEND); } } .fi .SH MEMORY USE When pausing a download transfer by returning the magic return code from a write callback, the read data is already in libcurl\(aqs internal buffers so it has to keep it in an allocated buffer until the receiving is again unpaused using this function. If the downloaded data is compressed and is asked to get uncompressed automatically on download, libcurl continues to uncompress the entire downloaded chunk and it caches the data uncompressed. This has the side\- effect that if you download something that is compressed a lot, it can result in a large data amount needing to be allocated to save the data during the pause. Consider not using paused receiving if you allow libcurl to uncompress data automatically. If the download is done with HTTP/2 or HTTP/3, there is up to a stream window size worth of data that curl cannot stop but instead needs to cache while the transfer is paused. This means that if a window size of 64 MB is used, libcurl might end up having to cache 64 MB of data. .SH AVAILABILITY Added in curl 7.18.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_reset (3)	4.86 KB	2025-07-08 09:41
📄 curl_easy_perform.3 .\" generated by cd2nroff 0.1 from curl_easy_perform.md .TH curl_easy_perform 3 "2025-06-27" libcurl .SH NAME curl_easy_perform \- perform a blocking network transfer .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_perform(CURL easy_handle); .fi .SH DESCRIPTION \fIcurl_easy_perform(3)\fP performs a network transfer in a blocking manner and returns when done, or earlier if it fails. For non\-blocking behavior, see \fIcurl_multi_perform(3)\fP. Invoke this function after \fIcurl_easy_init(3)\fP and all the \fIcurl_easy_setopt(3)\fP calls are made, and it performs the transfer as described in the options. It must be called with the same \fBeasy_handle\fP as input as the \fIcurl_easy_init(3)\fP call returned. You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the same \fBeasy_handle\fP. If you intend to transfer more than one file, you are even encouraged to do so. libcurl attempts to reuse existing connections for the following transfers, thus making the operations faster, less CPU intense and using less network resources. You probably want to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for the following \fIcurl_easy_perform(3)\fP call. You must never call this function simultaneously from two places using the same \fBeasy_handle\fP. Let the function return first before invoking it another time. If you want parallel transfers, you must use several curl easy_handles. A network transfer moves data to a peer or from a peer. An application tells libcurl how to receive data by setting the \fICURLOPT_WRITEFUNCTION(3)\fP and \fICURLOPT_WRITEDATA(3)\fP options. To tell libcurl what data to send, there are a few more alternatives but two common ones are \fICURLOPT_READFUNCTION(3)\fP and \fICURLOPT_POSTFIELDS(3)\fP. While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by \fIcurl_easy_perform(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_easy_init (3), .BR curl_easy_setopt (3), .BR curl_multi_add_handle (3), .BR curl_multi_perform (3), .BR libcurl-errors (3)	2.65 KB	2025-07-08 09:41
📄 curl_easy_recv.3 .\" generated by cd2nroff 0.1 from curl_easy_recv.md .TH curl_easy_recv 3 "2025-06-27" libcurl .SH NAME curl_easy_recv \- receives raw data on an "easy" connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_recv(CURL curl, void buffer, size_t buflen, size_t n); .fi .SH DESCRIPTION This function receives raw data from the established connection. You may use it together with \fIcurl_easy_send(3)\fP to implement custom protocols using libcurl. This functionality can be particularly useful if you use proxies and/or SSL encryption: libcurl takes care of proxy negotiation and connection setup. \fBbuffer\fP is a pointer to your buffer memory that gets populated by the received data. \fBbuflen\fP is the maximum amount of data you can get in that buffer. The variable \fBn\fP points to receives the number of received bytes. To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that \fIcurl_easy_recv(3)\fP does not work on connections that were created without this option. The call returns \fBCURLE_AGAIN\fP if there is no data to read \- the socket is used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use your operating system facilities like \fIselect(2)\fP to wait for data. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. Wait on the socket only if \fIcurl_easy_recv(3)\fP returns \fBCURLE_AGAIN\fP. The reason for this is libcurl or the SSL library may internally cache some data, therefore you should call \fIcurl_easy_recv(3)\fP until all data is read which would include any cached data. Furthermore if you wait on the socket and it tells you there is data to read, \fIcurl_easy_recv(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was read was for internal SSL processing, and no other data is available. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* Do not do the transfer - only connect to host / curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { char buf[256]; size_t nread; curl_socket_t sockfd; / Extract the socket from the curl handle - we need it for waiting. / res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); / read data / res = curl_easy_recv(curl, buf, sizeof(buf), &nread); } } } .fi .SH AVAILABILITY Added in curl 7.18.2 .SH RETURN VALUE On success, returns \fBCURLE_OK\fP, stores the received data into \fBbuffer\fP, and the number of bytes it actually read into \fBn\fP. On failure, returns the appropriate error code. The function may return \fBCURLE_AGAIN\fP. In this case, use your operating system facilities to wait until data can be read, and retry. Reading exactly 0 bytes indicates a closed connection. If there is no socket available to use from the previous transfer, this function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_perform (3), .BR curl_easy_send (3), .BR curl_easy_setopt (3)	3.23 KB	2025-07-08 09:41
📄 curl_easy_reset.3 .\" generated by cd2nroff 0.1 from curl_easy_reset.md .TH curl_easy_reset 3 "2025-06-27" libcurl .SH NAME curl_easy_reset \- reset all options of a libcurl session handle .SH SYNOPSIS .nf #include <curl/curl.h> void curl_easy_reset(CURL handle); .fi .SH DESCRIPTION Re\-initializes all options previously set on a specified curl handle to the default values. This puts back the handle to the same state as it was in when it was just created with \fIcurl_easy_init(3)\fP. It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies, the shares or the alt\-svc cache. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { /* ... the handle is used and options are set ... */ curl_easy_reset(curl); } } .fi .SH AVAILABILITY Added in curl 7.12.1 .SH RETURN VALUE Nothing .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_duphandle (3), .BR curl_easy_init (3), .BR curl_easy_setopt (3)	1.04 KB	2025-07-08 09:41
📄 curl_easy_send.3 .\" generated by cd2nroff 0.1 from curl_easy_send.md .TH curl_easy_send 3 "2025-06-27" libcurl .SH NAME curl_easy_send \- sends raw data over an "easy" connection .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_send(CURL curl, const void buffer, size_t buflen, size_t n); .fi .SH DESCRIPTION This function sends arbitrary data over the established connection. You may use it together with \fIcurl_easy_recv(3)\fP to implement custom protocols using libcurl. This functionality can be particularly useful if you use proxies and/or SSL encryption: libcurl takes care of proxy negotiation and connection setup. \fBbuffer\fP is a pointer to the data of length \fBbuflen\fP that you want sent. The variable \fBn\fP points to receives the number of sent bytes. To establish the connection, set \fICURLOPT_CONNECT_ONLY(3)\fP option before calling \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. Note that \fIcurl_easy_send(3)\fP does not work on connections that were created without this option. The call returns \fBCURLE_AGAIN\fP if it is not possible to send data right now - the socket is used in non\-blocking mode internally. When \fBCURLE_AGAIN\fP is returned, use your operating system facilities like \fIselect(2)\fP to wait until the socket is writable. The socket may be obtained using \fIcurl_easy_getinfo(3)\fP with \fICURLINFO_ACTIVESOCKET(3)\fP. Furthermore if you wait on the socket and it tells you it is writable, \fIcurl_easy_send(3)\fP may return \fBCURLE_AGAIN\fP if the only data that was sent was for internal SSL processing, and no other data could be sent. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); /* Do not do the transfer - only connect to host / curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 1L); res = curl_easy_perform(curl); if(res == CURLE_OK) { curl_socket_t sockfd; size_t sent; / Extract the socket from the curl handle - we need it for waiting. / res = curl_easy_getinfo(curl, CURLINFO_ACTIVESOCKET, &sockfd); / send data / res = curl_easy_send(curl, "hello", 5, &sent); } } } .fi .SH AVAILABILITY Added in curl 7.18.2 .SH RETURN VALUE On success, returns \fBCURLE_OK\fP and stores the number of bytes actually sent into \fBn\fP. Note that this may be less than the amount you wanted to send. On failure, returns the appropriate error code. This function may return \fBCURLE_AGAIN\fP. In this case, use your operating system facilities to wait until the socket is writable, and retry. If there is no socket available to use from the previous transfer, this function returns \fBCURLE_UNSUPPORTED_PROTOCOL\fP. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_perform (3), .BR curl_easy_recv (3), .BR curl_easy_setopt (3)	2.89 KB	2025-07-08 09:41
📄 curl_easy_setopt.3 .\" generated by cd2nroff 0.1 from curl_easy_setopt.md .TH curl_easy_setopt 3 "2025-06-27" libcurl .SH NAME curl_easy_setopt \- set options for a curl easy handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL handle, CURLoption option, parameter); .fi .SH DESCRIPTION \fIcurl_easy_setopt(3)\fP is used to tell libcurl how to behave. By setting the appropriate options, the application can change libcurl\(aqs behavior. All options are set with an \fIoption\fP followed by a \fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a \fBcurl_off_t\fP, depending on what the specific option expects. Read this manual carefully as bad input values may cause libcurl to behave badly. You can only set one option in each function call. A typical application uses many \fIcurl_easy_setopt(3)\fP calls in the setup phase. Options set with this function call are valid for all forthcoming transfers performed using this \fIhandle\fP. The options are not in any way reset between transfers, so if you want subsequent transfers with different options, you must change them between the transfers. You can optionally reset all options back to internal default with \fIcurl_easy_reset(3)\fP. Strings passed to libcurl as \(aqchar \(aq arguments, are copied by the library; the string storage associated to the pointer argument may be discarded or reused after \fIcurl_easy_setopt(3)\fP returns. The only exception to this rule is really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string \fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to read up on. This function does not accept input strings longer than \fBCURL_MAX_INPUT_LENGTH\fP (8 MB). The order in which the options are set does not matter. Before version 7.17.0, strings were not copied. Instead the user was forced keep them available until libcurl no longer needed them. The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or \fIcurl_easy_duphandle(3)\fP call. .SH OPTIONS .IP CURLOPT_ABSTRACT_UNIX_SOCKET Path to an abstract Unix domain socket. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP .IP CURLOPT_ACCEPTTIMEOUT_MS Timeout for waiting for the server\(aqs connect back to be accepted. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP .IP CURLOPT_ACCEPT_ENCODING Accept\-Encoding and automatic decompressing data. See \fICURLOPT_ACCEPT_ENCODING(3)\fP .IP CURLOPT_ADDRESS_SCOPE IPv6 scope for local addresses. See \fICURLOPT_ADDRESS_SCOPE(3)\fP .IP CURLOPT_ALTSVC Specify the Alt\-Svc: cache filename. See \fICURLOPT_ALTSVC(3)\fP .IP CURLOPT_ALTSVC_CTRL Enable and configure Alt\-Svc: treatment. See \fICURLOPT_ALTSVC_CTRL(3)\fP .IP CURLOPT_APPEND Append to remote file. See \fICURLOPT_APPEND(3)\fP .IP CURLOPT_AUTOREFERER Automatically set Referer: header. See \fICURLOPT_AUTOREFERER(3)\fP .IP CURLOPT_AWS_SIGV4 AWS HTTP V4 Signature. See \fICURLOPT_AWS_SIGV4(3)\fP .IP CURLOPT_BUFFERSIZE Ask for alternate buffer size. See \fICURLOPT_BUFFERSIZE(3)\fP .IP CURLOPT_CAINFO CA cert bundle. See \fICURLOPT_CAINFO(3)\fP .IP CURLOPT_CAINFO_BLOB CA cert bundle memory buffer. See \fICURLOPT_CAINFO_BLOB(3)\fP .IP CURLOPT_CAPATH Path to CA cert bundle. See \fICURLOPT_CAPATH(3)\fP .IP CURLOPT_CA_CACHE_TIMEOUT Timeout for CA cache. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP .IP CURLOPT_CERTINFO Extract certificate info. See \fICURLOPT_CERTINFO(3)\fP .IP CURLOPT_CHUNK_BGN_FUNCTION Callback for wildcard download start of chunk. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP .IP CURLOPT_CHUNK_DATA Data pointer to pass to the chunk callbacks. See \fICURLOPT_CHUNK_DATA(3)\fP .IP CURLOPT_CHUNK_END_FUNCTION Callback for wildcard download end of chunk. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP .IP CURLOPT_CLOSESOCKETDATA Data pointer to pass to the close socket callback. See \fICURLOPT_CLOSESOCKETDATA(3)\fP .IP CURLOPT_CLOSESOCKETFUNCTION Callback for closing socket. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP .IP CURLOPT_CONNECTTIMEOUT Timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT(3)\fP .IP CURLOPT_CONNECTTIMEOUT_MS Millisecond timeout for the connection phase. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP .IP CURLOPT_CONNECT_ONLY Only connect, nothing else. See \fICURLOPT_CONNECT_ONLY(3)\fP .IP CURLOPT_CONNECT_TO Connect to a specific host and port. See \fICURLOPT_CONNECT_TO(3)\fP .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION \fBOBSOLETE\fP Callback for code base conversion. See \fICURLOPT_CONV_FROM_NETWORK_FUNCTION(3)\fP .IP CURLOPT_CONV_FROM_UTF8_FUNCTION \fBOBSOLETE\fP Callback for code base conversion. See \fICURLOPT_CONV_FROM_UTF8_FUNCTION(3)\fP .IP CURLOPT_CONV_TO_NETWORK_FUNCTION \fBOBSOLETE\fP Callback for code base conversion. See \fICURLOPT_CONV_TO_NETWORK_FUNCTION(3)\fP .IP CURLOPT_COOKIE Cookie(s) to send. See \fICURLOPT_COOKIE(3)\fP .IP CURLOPT_COOKIEFILE File to read cookies from. See \fICURLOPT_COOKIEFILE(3)\fP .IP CURLOPT_COOKIEJAR File to write cookies to. See \fICURLOPT_COOKIEJAR(3)\fP .IP CURLOPT_COOKIELIST Add or control cookies. See \fICURLOPT_COOKIELIST(3)\fP .IP CURLOPT_COOKIESESSION Start a new cookie session. See \fICURLOPT_COOKIESESSION(3)\fP .IP CURLOPT_COPYPOSTFIELDS Send a POST with this data \- and copy it. See \fICURLOPT_COPYPOSTFIELDS(3)\fP .IP CURLOPT_CRLF Convert newlines. See \fICURLOPT_CRLF(3)\fP .IP CURLOPT_CRLFILE Certificate Revocation List. See \fICURLOPT_CRLFILE(3)\fP .IP CURLOPT_CURLU Set URL to work on with a URL handle. See \fICURLOPT_CURLU(3)\fP .IP CURLOPT_CUSTOMREQUEST Custom request/method. See \fICURLOPT_CUSTOMREQUEST(3)\fP .IP CURLOPT_DEBUGDATA Data pointer to pass to the debug callback. See \fICURLOPT_DEBUGDATA(3)\fP .IP CURLOPT_DEBUGFUNCTION Callback for debug information. See \fICURLOPT_DEBUGFUNCTION(3)\fP .IP CURLOPT_DEFAULT_PROTOCOL Default protocol. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP .IP CURLOPT_DIRLISTONLY List only. See \fICURLOPT_DIRLISTONLY(3)\fP .IP CURLOPT_DISALLOW_USERNAME_IN_URL Do not allow username in URL. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP .IP CURLOPT_DNS_CACHE_TIMEOUT Timeout for DNS cache. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP .IP CURLOPT_DNS_INTERFACE Bind name resolves to this interface. See \fICURLOPT_DNS_INTERFACE(3)\fP .IP CURLOPT_DNS_LOCAL_IP4 Bind name resolves to this IP4 address. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP .IP CURLOPT_DNS_LOCAL_IP6 Bind name resolves to this IP6 address. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP .IP CURLOPT_DNS_SERVERS Preferred DNS servers. See \fICURLOPT_DNS_SERVERS(3)\fP .IP CURLOPT_DNS_SHUFFLE_ADDRESSES Shuffle addresses before use. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP .IP CURLOPT_DNS_USE_GLOBAL_CACHE \fBOBSOLETE\fP Enable global DNS cache. See \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP .IP CURLOPT_DOH_SSL_VERIFYHOST Verify the hostname in the DoH (DNS\-over\-HTTPS) SSL certificate. See \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP .IP CURLOPT_DOH_SSL_VERIFYPEER Verify the DoH (DNS\-over\-HTTPS) SSL certificate. See \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP .IP CURLOPT_DOH_SSL_VERIFYSTATUS Verify the DoH (DNS\-over\-HTTPS) SSL certificate\(aqs status. See \fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP .IP CURLOPT_DOH_URL Use this DoH server for name resolves. See \fICURLOPT_DOH_URL(3)\fP .IP CURLOPT_ECH Set the configuration for ECH. See \fICURLOPT_ECH(3)\fP .IP CURLOPT_EGDSOCKET \fBOBSOLETE\fP Identify EGD socket for entropy. See \fICURLOPT_EGDSOCKET(3)\fP .IP CURLOPT_ERRORBUFFER Error message buffer. See \fICURLOPT_ERRORBUFFER(3)\fP .IP CURLOPT_EXPECT_100_TIMEOUT_MS 100\-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP .IP CURLOPT_FAILONERROR Fail on HTTP 4xx errors. \fICURLOPT_FAILONERROR(3)\fP .IP CURLOPT_FILETIME Request file modification date and time. See \fICURLOPT_FILETIME(3)\fP .IP CURLOPT_FNMATCH_DATA Data pointer to pass to the wildcard matching callback. See \fICURLOPT_FNMATCH_DATA(3)\fP .IP CURLOPT_FNMATCH_FUNCTION Callback for wildcard matching. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP .IP CURLOPT_FOLLOWLOCATION Follow HTTP redirects. See \fICURLOPT_FOLLOWLOCATION(3)\fP .IP CURLOPT_FORBID_REUSE Prevent subsequent connections from reusing this. See \fICURLOPT_FORBID_REUSE(3)\fP .IP CURLOPT_FRESH_CONNECT Use a new connection. \fICURLOPT_FRESH_CONNECT(3)\fP .IP CURLOPT_FTPPORT Use active FTP. See \fICURLOPT_FTPPORT(3)\fP .IP CURLOPT_FTPSSLAUTH Control how to do TLS. See \fICURLOPT_FTPSSLAUTH(3)\fP .IP CURLOPT_FTP_ACCOUNT Send ACCT command. See \fICURLOPT_FTP_ACCOUNT(3)\fP .IP CURLOPT_FTP_ALTERNATIVE_TO_USER Alternative to USER. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP .IP CURLOPT_FTP_CREATE_MISSING_DIRS Create missing directories on the remote server. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP .IP CURLOPT_FTP_FILEMETHOD Specify how to reach files. See \fICURLOPT_FTP_FILEMETHOD(3)\fP .IP CURLOPT_FTP_SKIP_PASV_IP Ignore the IP address in the PASV response. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP .IP CURLOPT_FTP_SSL_CCC Back to non\-TLS again after authentication. See \fICURLOPT_FTP_SSL_CCC(3)\fP .IP CURLOPT_FTP_USE_EPRT Use EPRT. See \fICURLOPT_FTP_USE_EPRT(3)\fP .IP CURLOPT_FTP_USE_EPSV Use EPSV. See \fICURLOPT_FTP_USE_EPSV(3)\fP .IP CURLOPT_FTP_USE_PRET Use PRET. See \fICURLOPT_FTP_USE_PRET(3)\fP .IP CURLOPT_GSSAPI_DELEGATION Disable GSS\-API delegation. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP .IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS Timeout for happy eyeballs. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP .IP CURLOPT_HAPROXYPROTOCOL Send an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP .IP CURLOPT_HAPROXY_CLIENT_IP Spoof the client IP in an HAProxy PROXY protocol v1 header. See \fICURLOPT_HAPROXY_CLIENT_IP(3)\fP .IP CURLOPT_HEADER Include the header in the body output. See \fICURLOPT_HEADER(3)\fP .IP CURLOPT_HEADERDATA Data pointer to pass to the header callback. See \fICURLOPT_HEADERDATA(3)\fP .IP CURLOPT_HEADERFUNCTION Callback for writing received headers. See \fICURLOPT_HEADERFUNCTION(3)\fP .IP CURLOPT_HEADEROPT Control custom headers. See \fICURLOPT_HEADEROPT(3)\fP .IP CURLOPT_HSTS Set HSTS cache file. See \fICURLOPT_HSTS(3)\fP .IP CURLOPT_HSTSREADDATA Pass pointer to the HSTS read callback. See \fICURLOPT_HSTSREADDATA(3)\fP .IP CURLOPT_HSTSREADFUNCTION Set HSTS read callback. See \fICURLOPT_HSTSREADFUNCTION(3)\fP .IP CURLOPT_HSTSWRITEDATA Pass pointer to the HSTS write callback. See \fICURLOPT_HSTSWRITEDATA(3)\fP .IP CURLOPT_HSTSWRITEFUNCTION Set HSTS write callback. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP .IP CURLOPT_HSTS_CTRL Enable HSTS. See \fICURLOPT_HSTS_CTRL(3)\fP .IP CURLOPT_HTTP09_ALLOWED Allow HTTP/0.9 responses. \fICURLOPT_HTTP09_ALLOWED(3)\fP .IP CURLOPT_HTTP200ALIASES Alternative versions of 200 OK. See \fICURLOPT_HTTP200ALIASES(3)\fP .IP CURLOPT_HTTPAUTH HTTP server authentication methods. See \fICURLOPT_HTTPAUTH(3)\fP .IP CURLOPT_HTTPGET Do an HTTP GET request. See \fICURLOPT_HTTPGET(3)\fP .IP CURLOPT_HTTPHEADER Custom HTTP headers. See \fICURLOPT_HTTPHEADER(3)\fP .IP CURLOPT_HTTPPOST \fBDeprecated option\fP Multipart formpost HTTP POST. See \fICURLOPT_HTTPPOST(3)\fP .IP CURLOPT_HTTPPROXYTUNNEL Tunnel through the HTTP proxy. \fICURLOPT_HTTPPROXYTUNNEL(3)\fP .IP CURLOPT_HTTP_CONTENT_DECODING Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP .IP CURLOPT_HTTP_TRANSFER_DECODING Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP .IP CURLOPT_HTTP_VERSION HTTP version to use. \fICURLOPT_HTTP_VERSION(3)\fP .IP CURLOPT_IGNORE_CONTENT_LENGTH Ignore Content\-Length. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP .IP CURLOPT_INFILESIZE Size of file to send. \fICURLOPT_INFILESIZE(3)\fP .IP CURLOPT_INFILESIZE_LARGE Size of file to send. \fICURLOPT_INFILESIZE_LARGE(3)\fP .IP CURLOPT_INTERFACE Bind connection locally to this. See \fICURLOPT_INTERFACE(3)\fP .IP CURLOPT_INTERLEAVEDATA Data pointer to pass to the RTSP interleave callback. See \fICURLOPT_INTERLEAVEDATA(3)\fP .IP CURLOPT_INTERLEAVEFUNCTION Callback for RTSP interleaved data. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP .IP CURLOPT_IOCTLDATA \fBDeprecated option\fP Data pointer to pass to the I/O callback. See \fICURLOPT_IOCTLDATA(3)\fP .IP CURLOPT_IOCTLFUNCTION \fBDeprecated option\fP Callback for I/O operations. See \fICURLOPT_IOCTLFUNCTION(3)\fP .IP CURLOPT_IPRESOLVE IP version to use. See \fICURLOPT_IPRESOLVE(3)\fP .IP CURLOPT_ISSUERCERT Issuer certificate. See \fICURLOPT_ISSUERCERT(3)\fP .IP CURLOPT_ISSUERCERT_BLOB Issuer certificate memory buffer. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP .IP CURLOPT_KEEP_SENDING_ON_ERROR Keep sending on HTTP >= 300 errors. \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP .IP CURLOPT_KEYPASSWD Client key password. See \fICURLOPT_KEYPASSWD(3)\fP .IP CURLOPT_KRBLEVEL Kerberos security level. See \fICURLOPT_KRBLEVEL(3)\fP .IP CURLOPT_LOCALPORT Bind connection locally to this port. See \fICURLOPT_LOCALPORT(3)\fP .IP CURLOPT_LOCALPORTRANGE Bind connection locally to port range. See \fICURLOPT_LOCALPORTRANGE(3)\fP .IP CURLOPT_LOGIN_OPTIONS Login options. See \fICURLOPT_LOGIN_OPTIONS(3)\fP .IP CURLOPT_LOW_SPEED_LIMIT Low speed limit to abort transfer. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP .IP CURLOPT_LOW_SPEED_TIME Time to be below the speed to trigger low speed abort. See \fICURLOPT_LOW_SPEED_TIME(3)\fP .IP CURLOPT_MAIL_AUTH Authentication address. See \fICURLOPT_MAIL_AUTH(3)\fP .IP CURLOPT_MAIL_FROM Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP .IP CURLOPT_MAIL_RCPT Address of the recipients. See \fICURLOPT_MAIL_RCPT(3)\fP .IP CURLOPT_MAIL_RCPT_ALLOWFAILS Allow RCPT TO command to fail for some recipients. See \fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP .IP CURLOPT_MAXAGE_CONN Limit the age (idle time) of connections for reuse. See \fICURLOPT_MAXAGE_CONN(3)\fP .IP CURLOPT_MAXCONNECTS Maximum number of connections in the connection pool. See \fICURLOPT_MAXCONNECTS(3)\fP .IP CURLOPT_MAXFILESIZE Maximum file size to get. See \fICURLOPT_MAXFILESIZE(3)\fP .IP CURLOPT_MAXFILESIZE_LARGE Maximum file size to get. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP .IP CURLOPT_MAXLIFETIME_CONN Limit the age (since creation) of connections for reuse. See \fICURLOPT_MAXLIFETIME_CONN(3)\fP .IP CURLOPT_MAXREDIRS Maximum number of redirects to follow. See \fICURLOPT_MAXREDIRS(3)\fP .IP CURLOPT_MAX_RECV_SPEED_LARGE Cap the download speed to this. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP .IP CURLOPT_MAX_SEND_SPEED_LARGE Cap the upload speed to this. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP .IP CURLOPT_MIMEPOST Post/send MIME data. See \fICURLOPT_MIMEPOST(3)\fP .IP CURLOPT_MIME_OPTIONS Set MIME option flags. See \fICURLOPT_MIME_OPTIONS(3)\fP .IP CURLOPT_NETRC Enable .netrc parsing. See \fICURLOPT_NETRC(3)\fP .IP CURLOPT_NETRC_FILE \&.netrc filename. See \fICURLOPT_NETRC_FILE(3)\fP .IP CURLOPT_NEW_DIRECTORY_PERMS Mode for creating new remote directories. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP .IP CURLOPT_NEW_FILE_PERMS Mode for creating new remote files. See \fICURLOPT_NEW_FILE_PERMS(3)\fP .IP CURLOPT_NOBODY Do not get the body contents. See \fICURLOPT_NOBODY(3)\fP .IP CURLOPT_NOPROGRESS Shut off the progress meter. See \fICURLOPT_NOPROGRESS(3)\fP .IP CURLOPT_NOPROXY Filter out hosts from proxy use. \fICURLOPT_NOPROXY(3)\fP .IP CURLOPT_NOSIGNAL Do not install signal handlers. See \fICURLOPT_NOSIGNAL(3)\fP .IP CURLOPT_OPENSOCKETDATA Data pointer to pass to the open socket callback. See \fICURLOPT_OPENSOCKETDATA(3)\fP .IP CURLOPT_OPENSOCKETFUNCTION Callback for socket creation. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP .IP CURLOPT_PASSWORD Password. See \fICURLOPT_PASSWORD(3)\fP .IP CURLOPT_PATH_AS_IS Disable squashing /../ and /./ sequences in the path. See \fICURLOPT_PATH_AS_IS(3)\fP .IP CURLOPT_PINNEDPUBLICKEY Set pinned SSL public key . See \fICURLOPT_PINNEDPUBLICKEY(3)\fP .IP CURLOPT_PIPEWAIT Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP .IP CURLOPT_PORT Port number to connect to. See \fICURLOPT_PORT(3)\fP .IP CURLOPT_POST Make an HTTP POST. See \fICURLOPT_POST(3)\fP .IP CURLOPT_POSTFIELDSIZE The POST data is this big. See \fICURLOPT_POSTFIELDSIZE(3)\fP .IP CURLOPT_POSTFIELDSIZE_LARGE The POST data is this big. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP .IP CURLOPT_POSTQUOTE Commands to run after transfer. See \fICURLOPT_POSTQUOTE(3)\fP .IP CURLOPT_POSTREDIR How to act on redirects after POST. See \fICURLOPT_POSTREDIR(3)\fP .IP CURLOPT_PREQUOTE Commands to run just before transfer. See \fICURLOPT_PREQUOTE(3)\fP .IP CURLOPT_PREREQDATA Data pointer to pass to the CURLOPT_PREREQFUNCTION callback. See \fICURLOPT_PREREQDATA(3)\fP .IP CURLOPT_PREREQFUNCTION Callback to be called after a connection is established but before a request is made on that connection. See \fICURLOPT_PREREQFUNCTION(3)\fP .IP CURLOPT_PRE_PROXY Socks proxy to use. See \fICURLOPT_PRE_PROXY(3)\fP .IP CURLOPT_PRIVATE Private pointer to store. See \fICURLOPT_PRIVATE(3)\fP .IP CURLOPT_PROGRESSDATA Data pointer to pass to the progress meter callback. See \fICURLOPT_PROGRESSDATA(3)\fP .IP CURLOPT_PROGRESSFUNCTION \fBOBSOLETE\fP callback for progress meter. See \fICURLOPT_PROGRESSFUNCTION(3)\fP .IP CURLOPT_PROTOCOLS \fBDeprecated option\fP Allowed protocols. See \fICURLOPT_PROTOCOLS(3)\fP .IP CURLOPT_PROTOCOLS_STR Allowed protocols. See \fICURLOPT_PROTOCOLS_STR(3)\fP .IP CURLOPT_PROXY Proxy to use. See \fICURLOPT_PROXY(3)\fP .IP CURLOPT_PROXYAUTH HTTP proxy authentication methods. See \fICURLOPT_PROXYAUTH(3)\fP .IP CURLOPT_PROXYHEADER Custom HTTP headers sent to proxy. See \fICURLOPT_PROXYHEADER(3)\fP .IP CURLOPT_PROXYPASSWORD Proxy password. See \fICURLOPT_PROXYPASSWORD(3)\fP .IP CURLOPT_PROXYPORT Proxy port to use. See \fICURLOPT_PROXYPORT(3)\fP .IP CURLOPT_PROXYTYPE Proxy type. See \fICURLOPT_PROXYTYPE(3)\fP .IP CURLOPT_PROXYUSERNAME Proxy username. See \fICURLOPT_PROXYUSERNAME(3)\fP .IP CURLOPT_PROXYUSERPWD Proxy username and password. See \fICURLOPT_PROXYUSERPWD(3)\fP .IP CURLOPT_PROXY_CAINFO Proxy CA cert bundle. See \fICURLOPT_PROXY_CAINFO(3)\fP .IP CURLOPT_PROXY_CAINFO_BLOB Proxy CA cert bundle memory buffer. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP .IP CURLOPT_PROXY_CAPATH Path to proxy CA cert bundle. See \fICURLOPT_PROXY_CAPATH(3)\fP .IP CURLOPT_PROXY_CRLFILE Proxy Certificate Revocation List. See \fICURLOPT_PROXY_CRLFILE(3)\fP .IP CURLOPT_PROXY_ISSUERCERT Proxy issuer certificate. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP .IP CURLOPT_PROXY_ISSUERCERT_BLOB Proxy issuer certificate memory buffer. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP .IP CURLOPT_PROXY_KEYPASSWD Proxy client key password. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP .IP CURLOPT_PROXY_PINNEDPUBLICKEY Set the proxy\(aqs pinned SSL public key. See \fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP .IP CURLOPT_PROXY_SERVICE_NAME Proxy authentication service name. \fICURLOPT_PROXY_SERVICE_NAME(3)\fP .IP CURLOPT_PROXY_SSLCERT Proxy client cert. See \fICURLOPT_PROXY_SSLCERT(3)\fP .IP CURLOPT_PROXY_SSLCERTTYPE Proxy client cert type. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP .IP CURLOPT_PROXY_SSLCERT_BLOB Proxy client cert memory buffer. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP .IP CURLOPT_PROXY_SSLKEY Proxy client key. See \fICURLOPT_PROXY_SSLKEY(3)\fP .IP CURLOPT_PROXY_SSLKEYTYPE Proxy client key type. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP .IP CURLOPT_PROXY_SSLKEY_BLOB Proxy client key. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP .IP CURLOPT_PROXY_SSLVERSION Proxy SSL version to use. See \fICURLOPT_PROXY_SSLVERSION(3)\fP .IP CURLOPT_PROXY_SSL_CIPHER_LIST Proxy ciphers to use. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP .IP CURLOPT_PROXY_SSL_OPTIONS Control proxy SSL behavior. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP .IP CURLOPT_PROXY_SSL_VERIFYHOST Verify the hostname in the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP .IP CURLOPT_PROXY_SSL_VERIFYPEER Verify the proxy SSL certificate. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP .IP CURLOPT_PROXY_TLS13_CIPHERS Proxy TLS 1.3 cipher suites to use. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP .IP CURLOPT_PROXY_TLSAUTH_PASSWORD Proxy TLS authentication password. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP .IP CURLOPT_PROXY_TLSAUTH_TYPE Proxy TLS authentication methods. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP .IP CURLOPT_PROXY_TLSAUTH_USERNAME Proxy TLS authentication username. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP .IP CURLOPT_PROXY_TRANSFER_MODE Add transfer mode to URL over proxy. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP .IP CURLOPT_PUT \fBDeprecated option\fP Issue an HTTP PUT request. See \fICURLOPT_PUT(3)\fP .IP CURLOPT_QUICK_EXIT To be set by toplevel tools like "curl" to skip lengthy cleanups when they are about to call exit() anyway. See \fICURLOPT_QUICK_EXIT(3)\fP .IP CURLOPT_QUOTE Commands to run before transfer. See \fICURLOPT_QUOTE(3)\fP .IP CURLOPT_RANDOM_FILE \fBOBSOLETE\fP Provide source for entropy random data. See \fICURLOPT_RANDOM_FILE(3)\fP .IP CURLOPT_RANGE Range requests. See \fICURLOPT_RANGE(3)\fP .IP CURLOPT_READDATA Data pointer to pass to the read callback. See \fICURLOPT_READDATA(3)\fP .IP CURLOPT_READFUNCTION Callback for reading data. See \fICURLOPT_READFUNCTION(3)\fP .IP CURLOPT_REDIR_PROTOCOLS \fBDeprecated option\fP Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS(3)\fP .IP CURLOPT_REDIR_PROTOCOLS_STR Protocols to allow redirects to. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP .IP CURLOPT_REFERER Referer: header. See \fICURLOPT_REFERER(3)\fP .IP CURLOPT_REQUEST_TARGET Set the request target. \fICURLOPT_REQUEST_TARGET(3)\fP .IP CURLOPT_RESOLVE Provide fixed/fake name resolves. See \fICURLOPT_RESOLVE(3)\fP .IP CURLOPT_RESOLVER_START_DATA Data pointer to pass to resolver start callback. See \fICURLOPT_RESOLVER_START_DATA(3)\fP .IP CURLOPT_RESOLVER_START_FUNCTION Callback to be called before a new resolve request is started. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP .IP CURLOPT_RESUME_FROM Resume a transfer. See \fICURLOPT_RESUME_FROM(3)\fP .IP CURLOPT_RESUME_FROM_LARGE Resume a transfer. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP .IP CURLOPT_RTSP_CLIENT_CSEQ Client CSEQ number. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP .IP CURLOPT_RTSP_REQUEST RTSP request. See \fICURLOPT_RTSP_REQUEST(3)\fP .IP CURLOPT_RTSP_SERVER_CSEQ CSEQ number for RTSP Server\->Client request. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP .IP CURLOPT_RTSP_SESSION_ID RTSP session\-id. See \fICURLOPT_RTSP_SESSION_ID(3)\fP .IP CURLOPT_RTSP_STREAM_URI RTSP stream URI. See \fICURLOPT_RTSP_STREAM_URI(3)\fP .IP CURLOPT_RTSP_TRANSPORT RTSP Transport: header. See \fICURLOPT_RTSP_TRANSPORT(3)\fP .IP CURLOPT_SASL_AUTHZID SASL authorization identity (identity to act as). See \fICURLOPT_SASL_AUTHZID(3)\fP .IP CURLOPT_SASL_IR Enable SASL initial response. See \fICURLOPT_SASL_IR(3)\fP .IP CURLOPT_SEEKDATA Data pointer to pass to the seek callback. See \fICURLOPT_SEEKDATA(3)\fP .IP CURLOPT_SEEKFUNCTION Callback for seek operations. See \fICURLOPT_SEEKFUNCTION(3)\fP .IP CURLOPT_SERVER_RESPONSE_TIMEOUT Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP .IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS Timeout for server responses. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP .IP CURLOPT_SERVICE_NAME Authentication service name. \fICURLOPT_SERVICE_NAME(3)\fP .IP CURLOPT_SHARE Share object to use. See \fICURLOPT_SHARE(3)\fP .IP CURLOPT_SOCKOPTDATA Data pointer to pass to the sockopt callback. See \fICURLOPT_SOCKOPTDATA(3)\fP .IP CURLOPT_SOCKOPTFUNCTION Callback for sockopt operations. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP .IP CURLOPT_SOCKS5_AUTH Socks5 authentication methods. See \fICURLOPT_SOCKS5_AUTH(3)\fP .IP CURLOPT_SOCKS5_GSSAPI_NEC Socks5 GSSAPI NEC mode. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP .IP CURLOPT_SOCKS5_GSSAPI_SERVICE \fBDeprecated option\fP Socks5 GSSAPI service name. See \fICURLOPT_SOCKS5_GSSAPI_SERVICE(3)\fP .IP CURLOPT_SSH_AUTH_TYPES SSH authentication types. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP .IP CURLOPT_SSH_COMPRESSION Enable SSH compression. See \fICURLOPT_SSH_COMPRESSION(3)\fP .IP CURLOPT_SSH_HOSTKEYDATA Custom pointer to pass to ssh host key callback. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP .IP CURLOPT_SSH_HOSTKEYFUNCTION Callback for checking host key handling. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 MD5 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP .IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 SHA256 of host\(aqs public key. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP .IP CURLOPT_SSH_KEYDATA Custom pointer to pass to ssh key callback. See \fICURLOPT_SSH_KEYDATA(3)\fP .IP CURLOPT_SSH_KEYFUNCTION Callback for known hosts handling. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP .IP CURLOPT_SSH_KNOWNHOSTS Filename with known hosts. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP .IP CURLOPT_SSH_PRIVATE_KEYFILE Filename of the private key. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP .IP CURLOPT_SSH_PUBLIC_KEYFILE Filename of the public key. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP .IP CURLOPT_SSLCERT Client cert. See \fICURLOPT_SSLCERT(3)\fP .IP CURLOPT_SSLCERTTYPE Client cert type. See \fICURLOPT_SSLCERTTYPE(3)\fP .IP CURLOPT_SSLCERT_BLOB Client cert memory buffer. See \fICURLOPT_SSLCERT_BLOB(3)\fP .IP CURLOPT_SSLENGINE Use identifier with SSL engine. See \fICURLOPT_SSLENGINE(3)\fP .IP CURLOPT_SSLENGINE_DEFAULT Default SSL engine. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP .IP CURLOPT_SSLKEY Client key. See \fICURLOPT_SSLKEY(3)\fP .IP CURLOPT_SSLKEYTYPE Client key type. See \fICURLOPT_SSLKEYTYPE(3)\fP .IP CURLOPT_SSLKEY_BLOB Client key memory buffer. See \fICURLOPT_SSLKEY_BLOB(3)\fP .IP CURLOPT_SSLVERSION SSL version to use. See \fICURLOPT_SSLVERSION(3)\fP .IP CURLOPT_SSL_CIPHER_LIST Ciphers to use. See \fICURLOPT_SSL_CIPHER_LIST(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_SSL_CTX_FUNCTION Callback for SSL context logic. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP .IP CURLOPT_SSL_EC_CURVES Set key exchange curves. See \fICURLOPT_SSL_EC_CURVES(3)\fP .IP CURLOPT_SSL_ENABLE_ALPN Enable use of ALPN. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP .IP CURLOPT_SSL_ENABLE_NPN \fBOBSOLETE\fP Enable use of NPN. See \fICURLOPT_SSL_ENABLE_NPN(3)\fP .IP CURLOPT_SSL_FALSESTART Enable TLS False Start. See \fICURLOPT_SSL_FALSESTART(3)\fP .IP CURLOPT_SSL_OPTIONS Control SSL behavior. See \fICURLOPT_SSL_OPTIONS(3)\fP .IP CURLOPT_SSL_SESSIONID_CACHE Disable SSL session\-id cache. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP .IP CURLOPT_SSL_SIGNATURE_ALGORITHMS TLS signature algorithms to use. See \fICURLOPT_SSL_SIGNATURE_ALGORITHMS(3)\fP .IP CURLOPT_SSL_VERIFYHOST Verify the hostname in the SSL certificate. See \fICURLOPT_SSL_VERIFYHOST(3)\fP .IP CURLOPT_SSL_VERIFYPEER Verify the SSL certificate. See \fICURLOPT_SSL_VERIFYPEER(3)\fP .IP CURLOPT_SSL_VERIFYSTATUS Verify the SSL certificate\(aqs status. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP .IP CURLOPT_STDERR Redirect stderr to another stream. See \fICURLOPT_STDERR(3)\fP .IP CURLOPT_STREAM_DEPENDS This HTTP/2 stream depends on another. See \fICURLOPT_STREAM_DEPENDS(3)\fP .IP CURLOPT_STREAM_DEPENDS_E This HTTP/2 stream depends on another exclusively. See \fICURLOPT_STREAM_DEPENDS_E(3)\fP .IP CURLOPT_STREAM_WEIGHT Set this HTTP/2 stream\(aqs weight. See \fICURLOPT_STREAM_WEIGHT(3)\fP .IP CURLOPT_SUPPRESS_CONNECT_HEADERS Suppress proxy CONNECT response headers from user callbacks. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP .IP CURLOPT_TCP_FASTOPEN Enable TCP Fast Open. See \fICURLOPT_TCP_FASTOPEN(3)\fP .IP CURLOPT_TCP_KEEPALIVE Enable TCP keep\-alive. See \fICURLOPT_TCP_KEEPALIVE(3)\fP .IP CURLOPT_TCP_KEEPCNT Maximum number of keep\-alive probes. See \fICURLOPT_TCP_KEEPCNT(3)\fP .IP CURLOPT_TCP_KEEPIDLE Idle time before sending keep\-alive. See \fICURLOPT_TCP_KEEPIDLE(3)\fP .IP CURLOPT_TCP_KEEPINTVL Interval between keep\-alive probes. See \fICURLOPT_TCP_KEEPINTVL(3)\fP .IP CURLOPT_TCP_NODELAY Disable the Nagle algorithm. See \fICURLOPT_TCP_NODELAY(3)\fP .IP CURLOPT_TELNETOPTIONS TELNET options. See \fICURLOPT_TELNETOPTIONS(3)\fP .IP CURLOPT_TFTP_BLKSIZE TFTP block size. See \fICURLOPT_TFTP_BLKSIZE(3)\fP .IP CURLOPT_TFTP_NO_OPTIONS Do not send TFTP options requests. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP .IP CURLOPT_TIMECONDITION Make a time conditional request. See \fICURLOPT_TIMECONDITION(3)\fP .IP CURLOPT_TIMEOUT Timeout for the entire request. See \fICURLOPT_TIMEOUT(3)\fP .IP CURLOPT_TIMEOUT_MS Millisecond timeout for the entire request. See \fICURLOPT_TIMEOUT_MS(3)\fP .IP CURLOPT_TIMEVALUE Time value for the time conditional request. See \fICURLOPT_TIMEVALUE(3)\fP .IP CURLOPT_TIMEVALUE_LARGE Time value for the time conditional request. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP .IP CURLOPT_TLS13_CIPHERS TLS 1.3 cipher suites to use. See \fICURLOPT_TLS13_CIPHERS(3)\fP .IP CURLOPT_TLSAUTH_PASSWORD TLS authentication password. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP .IP CURLOPT_TLSAUTH_TYPE TLS authentication methods. See \fICURLOPT_TLSAUTH_TYPE(3)\fP .IP CURLOPT_TLSAUTH_USERNAME TLS authentication username. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP .IP CURLOPT_TRAILERDATA Custom pointer passed to the trailing headers callback. See \fICURLOPT_TRAILERDATA(3)\fP .IP CURLOPT_TRAILERFUNCTION Set callback for sending trailing headers. See \fICURLOPT_TRAILERFUNCTION(3)\fP .IP CURLOPT_TRANSFERTEXT Use text transfer. See \fICURLOPT_TRANSFERTEXT(3)\fP .IP CURLOPT_TRANSFER_ENCODING Request Transfer\-Encoding. See \fICURLOPT_TRANSFER_ENCODING(3)\fP .IP CURLOPT_UNIX_SOCKET_PATH Path to a Unix domain socket. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP .IP CURLOPT_UNRESTRICTED_AUTH Do not restrict authentication to original host. \fICURLOPT_UNRESTRICTED_AUTH(3)\fP .IP CURLOPT_UPKEEP_INTERVAL_MS Sets the interval at which connection upkeep are performed. See \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP .IP CURLOPT_UPLOAD Upload data. See \fICURLOPT_UPLOAD(3)\fP .IP CURLOPT_UPLOAD_BUFFERSIZE Set upload buffer size. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP .IP CURLOPT_UPLOAD_FLAGS Set upload flags. See \fICURLOPT_UPLOAD_FLAGS(3)\fP .IP CURLOPT_URL URL to work on. See \fICURLOPT_URL(3)\fP .IP CURLOPT_USERAGENT User\-Agent: header. See \fICURLOPT_USERAGENT(3)\fP .IP CURLOPT_USERNAME Username. See \fICURLOPT_USERNAME(3)\fP .IP CURLOPT_USERPWD Username and password. See \fICURLOPT_USERPWD(3)\fP .IP CURLOPT_USE_SSL Use TLS/SSL. See \fICURLOPT_USE_SSL(3)\fP .IP CURLOPT_VERBOSE Display verbose information. See \fICURLOPT_VERBOSE(3)\fP .IP CURLOPT_WILDCARDMATCH Transfer multiple files according to a filename pattern. See \fICURLOPT_WILDCARDMATCH(3)\fP .IP CURLOPT_WRITEDATA Data pointer to pass to the write callback. See \fICURLOPT_WRITEDATA(3)\fP .IP CURLOPT_WRITEFUNCTION Callback for writing data. See \fICURLOPT_WRITEFUNCTION(3)\fP .IP CURLOPT_WS_OPTIONS Set WebSocket options. See \fICURLOPT_WS_OPTIONS(3)\fP .IP CURLOPT_XFERINFODATA Data pointer to pass to the progress meter callback. See \fICURLOPT_XFERINFODATA(3)\fP .IP CURLOPT_XFERINFOFUNCTION Callback for progress meter. See \fICURLOPT_XFERINFOFUNCTION(3)\fP .IP CURLOPT_XOAUTH2_BEARER OAuth2 bearer token. See \fICURLOPT_XOAUTH2_BEARER(3)\fP .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode res; curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); res = curl_easy_perform(curl); curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. Strings passed on to libcurl must be shorter than 8000000 bytes, otherwise \fIcurl_easy_setopt(3)\fP returns \fBCURLE_BAD_FUNCTION_ARGUMENT\fP (added in 7.65.0). \fBCURLE_BAD_FUNCTION_ARGUMENT\fP is returned when the argument to an option is invalid, like perhaps out of range. If you try to set an option that libcurl does not know about, perhaps because the library is too old to support it or the option was removed in a recent version, this function returns \fICURLE_UNKNOWN_OPTION\fP. If support for the option was disabled at compile\-time, it returns \fICURLE_NOT_BUILT_IN\fP. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_getinfo (3), .BR curl_easy_init (3), .BR curl_easy_option_by_id (3), .BR curl_easy_option_by_name (3), .BR curl_easy_option_next (3), .BR curl_easy_reset (3), .BR curl_multi_setopt (3)	31.71 KB	2025-07-08 09:41
📄 curl_easy_ssls_export.3 .\" generated by cd2nroff 0.1 from curl_easy_ssls_export.md .TH curl_easy_ssls_export 3 "2025-06-27" libcurl .SH NAME curl_easy_ssls_export \- export SSL sessions .SH SYNOPSIS .nf #include <curl/curl.h> typedef CURLcode curl_ssls_export_function(CURL handle, void userptr, const char session_key, const unsigned char shmac, size_t shmac_len, const unsigned char sdata, size_t sdata_len, curl_off_t valid_until, int ietf_tls_id, const char alpn, size_t earlydata_max); CURLcode curl_easy_ssls_export(CURL handle, curl_ssls_export_function export_fn, void userptr); .fi .SH DESCRIPTION This function iterates over all SSL session tickets that belong to the easy handle and invokes the \fBexport_fn\fP callback on each of them, as long as the callback returns \fBCURLE_OK\fP. The callback may then store this information and use \fIcurl_easy_ssls_import(3)\fP in another libcurl instance to add SSL session tickets again. Reuse of SSL session tickets may result in faster handshakes and some connections might be able to send request data in the initial packets (0\-RTT). From all the parameters passed to the \fBexport_fn\fP only two need to be persisted: either \fBsession_key\fP or \fBshamc\fP and always \fBsdata\fP. All other parameters are informative, e.g. allow the callback to act only on specific session tickets. Note that SSL sessions that involve a client certificate or SRP username/password are not exported. .SH Export Function Parameter .IP "Session Key" This is a printable, null\-terminated string that starts with \fBhostname:port\fP the session ticket is originating from and also contains all relevant SSL parameters used in the connection. The key also carries the name and version number of the TLS backend used. It is recommended to only persist \fBsession_key\fP when it can be protected from outside access. Since the hostname appears in plain text, it would allow any third party to see how curl has been used for. .IP "Salted Hash" A binary blob of \fBshmac_len\fP bytes that contains a random salt and a cryptographic hash of the salt and \fBsession_key\fP. The salt is generated for every session individually. Storing \fBshmac\fP is recommended when placing session tickets in a file, for example. A third party may brute\-force known hostnames, but cannot just "grep" for them. .IP "Session Data" A binary blob of \fBsdata_len\fP bytes, \fBsdata\fP contains all relevant SSL session ticket information for a later import \- apart from \fBsession_key\fP and \fBshmac\fP. .IP valid_until Seconds since EPOCH (1970\-01\-01) until the session ticket is considered valid. .IP "TLS Version" The IETF assigned number for the TLS version the session ticket originates from. This is \fB0x0304\fP for TLSv1.3, \fB0x0303\fP for 1.2, etc. Session tickets from version 1.3 have better security properties, so an export might store only those. .IP ALPN The ALPN protocol that had been negotiated with the host. This may be \fBNULL\fP if negotiation gave no result or had not been attempted. .IP "Early Data" The maximum amount of bytes the server supports to receive in early data (0\-RTT). This is 0 unless the server explicitly indicates support. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, GnuTLS, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf CURLcode my_export_cb(CURL handle, void userptr, const char session_key, const unsigned char shmac, size_t shmac_len, const unsigned char sdata, size_t sdata_len, curl_off_t valid_until, int ietf_tls_id, const char alpn, size_t earlydata_max) { / persist sdata / return CURLE_OK; } int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); CURLcode rc; CURL curl; sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_SHARE, share); rc = curl_easy_ssls_export(curl, my_export_cb, NULL); / always cleanup */ curl_easy_cleanup(curl); } curl_share_cleanup(share); } .fi .SH AVAILABILITY Added in curl 8.12.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR CURLOPT_SHARE (3), .BR curl_easy_ssls_import (3), .BR curl_share_setopt (3)	5.24 KB	2025-07-08 09:41
📄 curl_easy_ssls_import.3 .\" generated by cd2nroff 0.1 from curl_easy_ssls_import.md .TH curl_easy_ssls_import 3 "2025-06-27" libcurl .SH NAME curl_easy_ssls_export \- export SSL sessions .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_ssls_import(CURL handle, const char session_key, const unsigned char shmac, size_t shmac_len, const unsigned char sdata, size_t sdata_len); .fi .SH DESCRIPTION This function imports a previously exported SSL session ticket. \fBsdata\fP and \fBsdata_len\fP must always be provided. If \fBsession_key\fP is \fBNULL\fP, then \fBshmac\fP and \fBshmac_len\fP must be given as received during the export. See \fIcurl_easy_ssls_export(3)\fP for a description of those. Import of session tickets from other curl versions may fail due to changes in the handling of \fBshmac\fP or \fBsdata\fP. A session ticket which has already expired is silently discarded. .SH PROTOCOLS This functionality affects all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. This option works only with the following TLS backends: BearSSL, GnuTLS, OpenSSL, mbedTLS and wolfSSL .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); CURLcode rc; CURL curl; sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_SSL_SESSION); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); curl = curl_easy_init(); if(curl) { extern unsigned char shmac, sdata; size_t hlen = 4, slen = 5; curl_easy_setopt(curl, CURLOPT_SHARE, share); /* read shmac and sdata from storage / rc = curl_easy_ssls_import(curl, NULL, shmac, hlen, sdata, slen); / always cleanup */ curl_easy_cleanup(curl); } curl_share_cleanup(share); } .fi .SH AVAILABILITY Added in curl 8.12.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR CURLOPT_SHARE (3), .BR curl_easy_ssls_export (3), .BR curl_share_setopt (3)	2.22 KB	2025-07-08 09:41
📄 curl_easy_strerror.3 .\" generated by cd2nroff 0.1 from curl_easy_strerror.md .TH curl_easy_strerror 3 "2025-06-27" libcurl .SH NAME curl_easy_strerror \- return string describing error code .SH SYNOPSIS .nf #include <curl/curl.h> const char curl_easy_strerror(CURLcode errornum); .fi .SH DESCRIPTION The \fIcurl_easy_strerror(3)\fP function returns a string describing the CURLcode error code passed in the argument \fIerrornum\fP. Typically applications also appreciate \fICURLOPT_ERRORBUFFER(3)\fP for more specific error descriptions generated at runtime. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { CURLcode res; /* set options / / Perform the entire transfer / res = curl_easy_perform(curl); / Check for errors */ if(res != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\\n", curl_easy_strerror(res)); } } .fi .SH AVAILABILITY Added in curl 7.12.0 .SH RETURN VALUE A pointer to a null\-terminated string. .SH SEE ALSO .BR curl_multi_strerror (3), .BR curl_share_strerror (3), .BR curl_url_strerror (3), .BR libcurl-errors (3)	1.15 KB	2025-07-08 09:41
📄 curl_easy_unescape.3 .\" generated by cd2nroff 0.1 from curl_easy_unescape.md .TH curl_easy_unescape 3 "2025-06-27" libcurl .SH NAME curl_easy_unescape \- URL decode a string .SH SYNOPSIS .nf #include <curl/curl.h> char curl_easy_unescape(CURL curl, const char input, int inlength, int outlength); .fi .SH DESCRIPTION This function converts the URL encoded string \fBinput\fP to a "plain string" and returns that in an allocated memory area. All input characters that are URL encoded (%XX where XX is a two\-digit hexadecimal number) are converted to their binary versions. If the \fBlength\fP argument is set to 0 (zero), \fIcurl_easy_unescape(3)\fP uses strlen() on \fBinput\fP to find out the size. If \fBoutlength\fP is non\-NULL, the function writes the length of the returned string in the integer it points to. This allows proper handling even for strings containing %00. Since this is a pointer to an \fIint\fP type, it can only return a value up to \fIINT_MAX\fP so no longer string can be returned in this parameter. Since 7.82.0, the \fBcurl\fP parameter is ignored. Prior to that there was per\-handle character conversion support for some old operating systems such as TPF, but it was otherwise ignored. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { int decodelen; char decoded = curl_easy_unescape(curl, "%63%75%72%6c", 12, &decodelen); if(decoded) { /* do not assume printf() works on the decoded data / printf("Decoded: "); / ... */ curl_free(decoded); } curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE A pointer to a null\-terminated string or NULL if it failed. .SH SEE ALSO .BR curl_easy_escape (3), .BR curl_url_get (3)	1.87 KB	2025-07-08 09:41
📄 curl_easy_upkeep.3 .\" generated by cd2nroff 0.1 from curl_easy_upkeep.md .TH curl_easy_upkeep 3 "2025-06-27" libcurl .SH NAME curl_easy_upkeep \- keep existing connections alive .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_upkeep(CURL handle); .fi .SH DESCRIPTION Some protocols have "connection upkeep" mechanisms. These mechanisms usually send some traffic on existing connections in order to keep them alive; this can prevent connections from being closed due to overzealous firewalls, for example. For HTTP/2 we have an upkeep mechanism: when the connection upkeep interval is exceeded and \fIcurl_easy_upkeep(3)\fP is called, an HTTP/2 PING frame is sent on the connection. For MQTT the upkeep interval defines when to send ping requests to prevent the server from disconnecting. This function must be explicitly called in order to perform the upkeep work. The connection upkeep interval is set with \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. If you call this function on an easy handle that uses a shared connection cache then upkeep is performed on the connections in that cache, even if those connections were never used by the easy handle. (Added in 8.10.0) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { /* Make a connection to an HTTP/2 server. / curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); / Set the interval to 30000ms / 30s / curl_easy_setopt(curl, CURLOPT_UPKEEP_INTERVAL_MS, 30000L); curl_easy_perform(curl); / Perform more work here. / / While the connection is being held open, curl_easy_upkeep() can be called. If curl_easy_upkeep() is called and the time since the last upkeep exceeds the interval, then an HTTP/2 PING is sent. / curl_easy_upkeep(curl); / Perform more work here. / / always cleanup */ curl_easy_cleanup(curl); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR CURLOPT_TCP_KEEPALIVE (3), .BR CURLOPT_TCP_KEEPIDLE (3)	2.33 KB	2025-07-08 09:41
📄 curl_escape.3 .\" generated by cd2nroff 0.1 from curl_escape.md .TH curl_escape 3 "2025-06-27" libcurl .SH NAME curl_escape \- URL encode a string .SH SYNOPSIS .nf #include <curl/curl.h> char curl_escape(const char string, int length); .fi .SH DESCRIPTION Obsolete function. Use \fIcurl_easy_escape(3)\fP instead. This function converts the given input \fBstring\fP to a URL encoded string and return that as a new allocated string. All input characters that are not a\-z, A\-Z or 0\-9 are converted to their "URL escaped" version (\fB%NN\fP where \fBNN\fP is a two\-digit hexadecimal number). If the \fBlength\fP argument is set to 0, \fIcurl_escape(3)\fP uses strlen() on \fBstring\fP to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { char *output = curl_escape("data to convert", 15); if(output) { printf("Encoded: %s\\n", output); curl_free(output); } } .fi .SH HISTORY Since 7.15.4, \fIcurl_easy_escape(3)\fP should be used. This function might be removed in a future release. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE A pointer to a null\-terminated string or NULL if it failed. .SH SEE ALSO .BR curl_free (3), .BR curl_unescape (3)	1.27 KB	2025-07-08 09:41
📄 curl_formadd.3 .\" generated by cd2nroff 0.1 from curl_formadd.md .TH curl_formadd 3 "2025-06-27" libcurl .SH NAME curl_formadd \- add a section to a multipart form POST .SH SYNOPSIS .nf #include <curl/curl.h> CURLFORMcode curl_formadd(struct curl_httppost firstitem, struct curl_httppost lastitem, ...); .fi .SH DESCRIPTION \fBThis function is deprecated.\fP Use \fIcurl_mime_init(3)\fP instead. curl_formadd() is used to append sections when building a multipart form post. Append one section at a time until you have added all the sections you want included and then you pass the \fIfirstitem\fP pointer as parameter to \fICURLOPT_HTTPPOST(3)\fP. \fIlastitem\fP is set after each \fIcurl_formadd(3)\fP call and on repeated invokes it should be left as set to allow repeated invokes to find the end of the list faster. After the \fIlastitem\fP pointer follow the real arguments. The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to NULL in the first call to this function. All list\-data is allocated by the function itself. You must call \fIcurl_formfree(3)\fP on the \fIfirstitem\fP after the form post has been done to free the resources. Using POST with HTTP 1.1 implies the use of a "Expect: 100\-continue" header. You can disable this header with \fICURLOPT_HTTPHEADER(3)\fP as usual. First, there are some basics you need to understand about multipart form posts. Each part consists of at least a NAME and a CONTENTS part. If the part is made for file upload, there are also a stored CONTENT\-TYPE and a FILENAME. Below, we discuss what options you use to set these properties in the parts you want to add to your post. The options listed first are for making normal parts. The options from \fICURLFORM_FILE\fP through \fICURLFORM_BUFFERLENGTH\fP are for file upload parts. .SH OPTIONS .IP CURLFORM_COPYNAME followed by a string which provides the \fIname\fP of this part. libcurl copies the string so your application does not need to keep it around after this function call. If the name is not null\-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain zero\-valued bytes. The copied data is freed by \fIcurl_formfree(3)\fP. .IP CURLFORM_PTRNAME followed by a string which provides the \fIname\fP of this part. libcurl uses the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the name is not null\-terminated, you must set its length with \fBCURLFORM_NAMELENGTH\fP. The \fIname\fP is not allowed to contain zero\-valued bytes. .IP CURLFORM_COPYCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl copies the provided data, so your application does not need to keep it around after this function call. If the data is not null\-terminated, or if you would like it to contain zero bytes, you must set the length of the name with \fBCURLFORM_CONTENTSLENGTH\fP. The copied data is freed by \fIcurl_formfree(3)\fP. .IP CURLFORM_PTRCONTENTS followed by a pointer to the contents of this part, the actual data to send away. libcurl uses the pointer and refer to the data in your application, so you must make sure it remains until curl no longer needs it. If the data is not null\-terminated, or if you would like it to contain zero bytes, you must set its length with \fBCURLFORM_CONTENTSLENGTH\fP. .IP CURLFORM_CONTENTLEN followed by a curl_off_t value giving the length of the contents. Note that for \fICURLFORM_STREAM\fP contents, this option is mandatory. If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents to figure out the size. If you really want to send a zero byte content then you must make sure strlen() on the data pointer returns zero. (Option added in 7.46.0) .IP CURLFORM_CONTENTSLENGTH (This option is deprecated. Use \fICURLFORM_CONTENTLEN\fP instead.) followed by a long giving the length of the contents. Note that for \fICURLFORM_STREAM\fP contents, this option is mandatory. If you pass a 0 (zero) for this option, libcurl calls strlen() on the contents to figure out the size. If you really want to send a zero byte content then you must make sure strlen() on the data pointer returns zero. .IP CURLFORM_FILECONTENT followed by a filename, causes that file to be read and its contents used as data in this part. This part does \fInot\fP automatically become a file upload part simply because its data was read from a file. The specified file needs to kept around until the associated transfer is done. .IP CURLFORM_FILE followed by a filename, makes this part a file upload part. It sets the \fIfilename\fP field to the basename of the provided filename, it reads the contents of the file and passes them as data and sets the content\-type if the given file match one of the internally known file extensions. For \fBCURLFORM_FILE\fP the user may send one or more files in one part by providing multiple \fBCURLFORM_FILE\fP arguments each followed by the filename (and each \fICURLFORM_FILE\fP is allowed to have a \fICURLFORM_CONTENTTYPE\fP). The given upload file has to exist in its full in the file system already when the upload starts, as libcurl needs to read the correct file size beforehand. The specified file needs to kept around until the associated transfer is done. .IP CURLFORM_CONTENTTYPE is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string which provides the content\-type for this part, possibly instead of an internally chosen one. .IP CURLFORM_FILENAME is used in combination with \fICURLFORM_FILE\fP. Followed by a pointer to a string, it tells libcurl to use the given string as the \fIfilename\fP in the file upload part instead of the actual filename. .IP CURLFORM_BUFFER is used for custom file upload parts without use of \fICURLFORM_FILE\fP. It tells libcurl that the file contents are already present in a buffer. The parameter is a string which provides the \fIfilename\fP field in the content header. .IP CURLFORM_BUFFERPTR is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a pointer to the buffer to be uploaded. This buffer must not be freed until after \fIcurl_easy_cleanup(3)\fP is called. You must also use \fICURLFORM_BUFFERLENGTH\fP to set the number of bytes in the buffer. .IP CURLFORM_BUFFERLENGTH is used in combination with \fICURLFORM_BUFFER\fP. The parameter is a long which gives the length of the buffer. .IP CURLFORM_STREAM Tells libcurl to use the \fICURLOPT_READFUNCTION(3)\fP callback to get data. The parameter you pass to \fICURLFORM_STREAM\fP is the pointer passed on to the read callback\(aqs fourth argument. If you want the part to look like a file upload one, set the \fICURLFORM_FILENAME\fP parameter as well. Note that when using \fICURLFORM_STREAM\fP, \fICURLFORM_CONTENTSLENGTH\fP must also be set with the total expected length of the part unless the formpost is sent chunked encoded. (Option added in libcurl 7.18.2) .IP CURLFORM_ARRAY Another possibility to send options to curl_formadd() is the \fBCURLFORM_ARRAY\fP option, that passes a struct curl_forms array pointer as its value. Each curl_forms structure element has a \fICURLformoption\fP and a char pointer. The final element in the array must be a CURLFORM_END. All available options can be used in an array, except the CURLFORM_ARRAY option itself. The last argument in such an array must always be \fBCURLFORM_END\fP. .IP CURLFORM_CONTENTHEADER specifies extra headers for the form POST section. This takes a curl_slist prepared in the usual way using \fBcurl_slist_append\fP and appends the list of headers to those libcurl automatically generates. The list must exist while the POST occurs, if you free it before the post completes you may experience problems. When you have passed the \fIstruct curl_httppost\fP pointer to \fIcurl_easy_setopt(3)\fP (using the \fICURLOPT_HTTPPOST(3)\fP option), you must not free the list until after you have called \fIcurl_easy_cleanup(3)\fP for the curl handle. See example below. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf #include <string.h> /* for strlen / static const char record[]="data in a buffer"; int main(void) { CURL curl = curl_easy_init(); if(curl) { struct curl_httppost post = NULL; struct curl_httppost last = NULL; char namebuffer[] = "name buffer"; long namelength = strlen(namebuffer); char buffer[] = "test buffer"; char htmlbuffer[] = "<HTML>test buffer</HTML>"; long htmlbufferlength = strlen(htmlbuffer); struct curl_forms forms[3]; char file1[] = "my-face.jpg"; char file2[] = "your-face.jpg"; /* add null character into htmlbuffer, to demonstrate that transfers of buffers containing null characters actually work / htmlbuffer[8] = '\\0'; / Add simple name/content section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", CURLFORM_COPYCONTENTS, "content", CURLFORM_END); / Add simple name/content/contenttype section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "htmlcode", CURLFORM_COPYCONTENTS, "<HTML></HTML>", CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); / Add name/ptrcontent section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "name_for_ptrcontent", CURLFORM_PTRCONTENTS, buffer, CURLFORM_END); / Add ptrname/ptrcontent section / curl_formadd(&post, &last, CURLFORM_PTRNAME, namebuffer, CURLFORM_PTRCONTENTS, buffer, CURLFORM_NAMELENGTH, namelength, CURLFORM_END); / Add name/ptrcontent/contenttype section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "html_code_with_hole", CURLFORM_PTRCONTENTS, htmlbuffer, CURLFORM_CONTENTSLENGTH, htmlbufferlength, CURLFORM_CONTENTTYPE, "text/html", CURLFORM_END); / Add simple file section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", CURLFORM_FILE, "my-face.jpg", CURLFORM_END); / Add file/contenttype section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "picture", CURLFORM_FILE, "my-face.jpg", CURLFORM_CONTENTTYPE, "image/jpeg", CURLFORM_END); / Add two file section / curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", CURLFORM_FILE, "my-face.jpg", CURLFORM_FILE, "your-face.jpg", CURLFORM_END); / Add two file section using CURLFORM_ARRAY / forms[0].option = CURLFORM_FILE; forms[0].value = file1; forms[1].option = CURLFORM_FILE; forms[1].value = file2; forms[2].option = CURLFORM_END; / Add a buffer to upload / curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", CURLFORM_BUFFER, "data", CURLFORM_BUFFERPTR, record, CURLFORM_BUFFERLENGTH, sizeof(record), CURLFORM_END); / no option needed for the end marker / curl_formadd(&post, &last, CURLFORM_COPYNAME, "pictures", CURLFORM_ARRAY, forms, CURLFORM_END); / Add the content of a file as a normal post text value / curl_formadd(&post, &last, CURLFORM_COPYNAME, "filecontent", CURLFORM_FILECONTENT, ".bashrc", CURLFORM_END); / Set the form info / curl_easy_setopt(curl, CURLOPT_HTTPPOST, post); curl_easy_perform(curl); curl_easy_cleanup(curl); curl_formfree(post); } } .fi .SH DEPRECATED Deprecated in 7.56.0. Before this release, field names were allowed to contain zero\-valued bytes. The pseudo\-filename "\-" to read stdin is discouraged although still supported, but data is not read before being actually sent: the effective data size can then not be automatically determined, resulting in a chunked encoding transfer. Backslashes and double quotes in field and filenames are now escaped before transmission. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE 0 means everything was OK, non\-zero means an error occurred corresponding to a \fICURL_FORMADD_\fI\fP constant defined in \fP<curl/curl.h>. .SH SEE ALSO .BR curl_easy_setopt (3), .BR curl_formfree (3), .BR curl_mime_init (3)	12 KB	2025-07-08 09:41
📄 curl_formfree.3 .\" generated by cd2nroff 0.1 from curl_formfree.md .TH curl_formfree 3 "2025-06-27" libcurl .SH NAME curl_formfree \- free a previously build multipart form post chain .SH SYNOPSIS .nf #include <curl/curl.h> void curl_formfree(struct curl_httppost form); .fi .SH DESCRIPTION This function is deprecated. Do not use. See \fIcurl_mime_init(3)\fP instead. curl_formfree() is used to clean up data previously built/appended with \fIcurl_formadd(3)\fP. This must be called when the data has been used, which typically means after \fIcurl_easy_perform(3)\fP has been called. The pointer to free is the same pointer you passed to the \fICURLOPT_HTTPPOST(3)\fP option, which is the \fIfirstitem\fP pointer from the \fIcurl_formadd(3)\fP invoke(s). \fBform\fP is the pointer as returned from a previous call to \fIcurl_formadd(3)\fP and may be NULL. Passing in a NULL pointer in \fIform\fP makes this function return immediately with no action. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { struct curl_httppost formpost; struct curl_httppost lastptr; /* Fill in a file upload field / curl_formadd(&formpost, &lastptr, CURLFORM_COPYNAME, "file", CURLFORM_FILE, "nice-image.jpg", CURLFORM_END); curl_easy_setopt(curl, CURLOPT_HTTPPOST, formpost); curl_easy_perform(curl); / then cleanup the formpost chain */ curl_formfree(formpost); } } .fi .SH DEPRECATED Deprecated in 7.56.0. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE None .SH SEE ALSO .BR curl_formadd (3), .BR curl_mime_free (3), .BR curl_mime_init (3)	1.67 KB	2025-07-08 09:41
📄 curl_formget.3 .\" generated by cd2nroff 0.1 from curl_formget.md .TH curl_formget 3 "2025-06-27" libcurl .SH NAME curl_formget \- serialize a multipart form POST chain .SH SYNOPSIS .nf #include <curl/curl.h> int curl_formget(struct curl_httppost * form, void userp, curl_formget_callback append); .fi .SH DESCRIPTION The form API (including this function) is deprecated since libcurl 7.56.0. curl_formget() serializes data previously built with \fIcurl_formadd(3)\fP. It accepts a void pointer as second argument named \fIuserp\fP which is passed as the first argument to the curl_formget_callback function. .nf typedef size_t (curl_formget_callback)(void userp, const char buf, size_t len);" .fi The \fIcurl_formget_callback\fP is invoked for each part of the HTTP POST chain. The character buffer passed to the callback must not be freed. The callback should return the buffer length passed to it on success. If the \fBCURLFORM_STREAM\fP option is used in the formpost, it prevents \fIcurl_formget(3)\fP from working until you have performed the actual HTTP request. This, because first then does libcurl known which actual read callback to use. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf size_t print_httppost_callback(void arg, const char buf, size_t len) { fwrite(buf, len, 1, stdout); ((size_t ) arg) += len; return len; } size_t print_httppost(struct curl_httppost *post) { size_t total_size = 0; if(curl_formget(post, &total_size, print_httppost_callback)) { return (size_t) -1; } return total_size; } .fi .SH AVAILABILITY Added in curl 7.15.5 .SH RETURN VALUE 0 means everything was OK, non\-zero means an error occurred .SH SEE ALSO .BR curl_formadd (3), .BR curl_mime_init (3)	1.75 KB	2025-07-08 09:41
📄 curl_free.3 .\" generated by cd2nroff 0.1 from curl_free.md .TH curl_free 3 "2025-06-27" libcurl .SH NAME curl_free \- reclaim memory that has been obtained through a libcurl call .SH SYNOPSIS .nf #include <curl/curl.h> void curl_free(void ptr); .fi .SH DESCRIPTION curl_free reclaims memory that has been obtained through a libcurl call. Use \fIcurl_free(3)\fP instead of free() to avoid anomalies that can result from differences in memory management between your application and libcurl. Passing in a NULL pointer in \fIptr\fP makes this function return immediately with no action. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { char width = curl_getenv("COLUMNS"); if(width) { /* it was set */ curl_free(width); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE None .SH SEE ALSO .BR curl_easy_escape (3), .BR curl_easy_unescape (3)	904 B	2025-07-08 09:41
📄 curl_getdate.3 .\" generated by cd2nroff 0.1 from curl_getdate.md .TH curl_getdate 3 "2025-06-27" libcurl .SH NAME curl_getdate \- convert date string to number of seconds .SH SYNOPSIS .nf #include <curl/curl.h> time_t curl_getdate(const char datestring, const time_t now); .fi .SH DESCRIPTION \fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January 1st 1970 00:00:00 in the UTC time zone, for the date and time that the \fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used, pass a NULL there. This function works with valid dates and does not always detect and reject wrong dates, such as February 30. .SH PARSING DATES AND TIMES A "date" is a string containing several items separated by whitespace. The order of the items is immaterial. A date string may contain many flavors of items: .IP "calendar date items" Can be specified several ways. Month names can only be three\-letter English abbreviations, numbers can be zero\-prefixed and the year may use 2 or 4 digits. Examples: 06 Nov 1994, 06\-Nov\-94 and Nov\-94 6. If the year appears to be below 100 (two\-digit), any year after 70 is assumed to be 1900 + the given year. All others are 2000 + the given year. .IP "time of the day items" This string specifies the time on a given day. You must specify it with 6 digits with two colons: HH:MM:SS. If there is no time given in a provided date string, 00:00:00 is assumed. Example: 18:19:21. .IP "time zone items" Specifies international time zone. There are a few acronyms supported, but in general you should instead use the specific relative time compared to UTC. Supported formats include: \-1200, MST, +0100. .IP "day of the week items" Specifies a day of the week. Days of the week may be spelled out in full (using English): \(aqSunday\(aq, \(aqMonday\(aq, etc or they may be abbreviated to their first three letters. This is usually not info that adds anything. .IP "pure numbers" If a decimal number of the form YYYYMMDD appears, then YYYY is read as the year, MM as the month number and DD as the day of the month, for the specified calendar date. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { time_t t; t = curl_getdate("Sun, 06 Nov 1994 08:49:37 GMT", NULL); t = curl_getdate("Sunday, 06-Nov-94 08:49:37 GMT", NULL); t = curl_getdate("Sun Nov 6 08:49:37 1994", NULL); t = curl_getdate("06 Nov 1994 08:49:37 GMT", NULL); t = curl_getdate("06-Nov-94 08:49:37 GMT", NULL); t = curl_getdate("Nov 6 08:49:37 1994", NULL); t = curl_getdate("06 Nov 1994 08:49:37", NULL); t = curl_getdate("06-Nov-94 08:49:37", NULL); t = curl_getdate("1994 Nov 6 08:49:37", NULL); t = curl_getdate("GMT 08:49:37 06-Nov-94 Sunday", NULL); t = curl_getdate("94 6 Nov 08:49:37", NULL); t = curl_getdate("1994 Nov 6", NULL); t = curl_getdate("06-Nov-94", NULL); t = curl_getdate("Sun Nov 6 94", NULL); t = curl_getdate("1994.Nov.6", NULL); t = curl_getdate("Sun/Nov/6/94/GMT", NULL); t = curl_getdate("Sun, 06 Nov 1994 08:49:37 CET", NULL); t = curl_getdate("06 Nov 1994 08:49:37 EST", NULL); t = curl_getdate("Sun, 12 Sep 2004 15:05:58 -0700", NULL); t = curl_getdate("Sat, 11 Sep 2004 21:32:11 +0200", NULL); t = curl_getdate("20040912 15:05:58 -0700", NULL); t = curl_getdate("20040911 +0200", NULL); } .fi .SH STANDARDS This parser handles date formats specified in RFC 822 (including the update in RFC 1123) using time zone name or time zone delta and RFC 850 (obsoleted by RFC 1036) and ANSI C\(aqs \fIasctime()\fP format. These formats are the only ones RFC 7231 says HTTP applications may use. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE This function returns \-1 when it fails to parse the date string. Otherwise it returns the number of seconds as described. On systems with a signed 32\-bit time_t: if the year is larger than 2037 or less than 1903, this function returns \-1. On systems with an unsigned 32\-bit time_t: if the year is larger than 2106 or less than 1970, this function returns \-1. On systems with 64\-bit time_t: if the year is less than 1583, this function returns \-1. (The Gregorian calendar was first introduced 1582 so no "real" dates in this way of doing dates existed before then.) .SH SEE ALSO .BR CURLOPT_TIMECONDITION (3), .BR CURLOPT_TIMEVALUE (3), .BR curl_easy_escape (3), .BR curl_easy_unescape (3)	4.27 KB	2025-07-08 09:41
📄 curl_getenv.3 .\" generated by cd2nroff 0.1 from curl_getenv.md .TH curl_getenv 3 "2025-06-27" libcurl .SH NAME curl_getenv \- return value for environment name .SH SYNOPSIS .nf #include <curl/curl.h> char curl_getenv(const char name); .fi .SH DESCRIPTION curl_getenv() is a portable wrapper for the getenv() function, meant to emulate its behavior and provide an identical interface for all operating systems libcurl builds on (including Windows). You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { char width = curl_getenv("COLUMNS"); if(width) { / it was set */ curl_free(width); } } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE A pointer to a null\-terminated string or NULL if it failed to find the specified name. .SH NOTE Under Unix operating systems, there is no point in returning an allocated memory, although other systems does not work properly if this is not done. The Unix implementation thus suffers slightly from the drawbacks of other systems. .SH SEE ALSO .BR getenv (3C)	1.1 KB	2025-07-08 09:41
📄 curl_global_cleanup.3 .\" generated by cd2nroff 0.1 from curl_global_cleanup.md .TH curl_global_cleanup 3 "2025-06-27" libcurl .SH NAME curl_global_cleanup \- global libcurl cleanup .SH SYNOPSIS .nf #include <curl/curl.h> void curl_global_cleanup(void); .fi .SH DESCRIPTION This function releases resources acquired by \fIcurl_global_init(3)\fP. You should call \fIcurl_global_cleanup(3)\fP once for each call you make to \fIcurl_global_init(3)\fP, after you are done using libcurl. This function is thread\-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set (most platforms). If this is not thread\-safe, you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. Because \fIcurl_global_cleanup(3)\fP calls functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries. See the description in \fIlibcurl(3)\fP of global environment requirements for details of how to use this function. .SH CAUTION \fIcurl_global_cleanup(3)\fP does not block waiting for any libcurl\-created threads to terminate (such as threads used for name resolving). If a module containing libcurl is dynamically unloaded while libcurl\-created threads are still running then your program may crash or other corruption may occur. We recommend you do not run libcurl from any module that may be unloaded dynamically. This behavior may be addressed in the future. libcurl may not be able to fully clean up after multi\-threaded OpenSSL depending on how OpenSSL was built and loaded as a library. It is possible in some rare circumstances a memory leak could occur unless you implement your own OpenSSL thread cleanup. Refer to \fIlibcurl\-thread(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { curl_global_init(CURL_GLOBAL_DEFAULT); /* use libcurl, then before exiting... */ curl_global_cleanup(); } .fi .SH AVAILABILITY Added in curl 7.8 .SH RETURN VALUE None .SH SEE ALSO .BR curl_global_init (3), .BR libcurl (3), .BR libcurl-thread (3)	2.16 KB	2025-07-08 09:41
📄 curl_global_init.3 .\" generated by cd2nroff 0.1 from curl_global_init.md .TH curl_global_init 3 "2025-06-27" libcurl .SH NAME curl_global_init \- global libcurl initialization .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_global_init(long flags); .fi .SH DESCRIPTION This function sets up the program environment that libcurl needs. Think of it as an extension of the library loader. This function must be called at least once within a program (a program is all the code that shares a memory space) before the program calls any other function in libcurl. The environment it sets up is constant for the life of the program and is the same for every program, so multiple calls have the same effect as one call. The flags option is a bit pattern that tells libcurl exactly what features to init, as described below. Set the desired bits by ORing the values together. In normal operation, you must specify CURL_GLOBAL_ALL. Do not use any other value unless you are familiar with it and mean to control internal operations of libcurl. This function is thread\-safe on most platforms. Then \fIcurl_version_info(3)\fP has the \fIthreadsafe\fP feature set (added in 7.84.0). If this is not thread\-safe (the bit mentioned above is not set), you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. Because \fIcurl_global_init(3)\fP calls functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries. If you are initializing libcurl from a Windows DLL you should not initialize it from \fIDllMain\fP or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock. See the description in \fIlibcurl(3)\fP of global environment requirements for details of how to use this function. .SH FLAGS .IP CURL_GLOBAL_ALL Initialize everything possible. This sets all known bits except \fBCURL_GLOBAL_ACK_EINTR\fP. .IP CURL_GLOBAL_SSL (This flag\(aqs presence or absence serves no meaning since 7.57.0. The description below is for older libcurl versions.) Initialize SSL. The implication here is that if this bit is not set, the initialization of the SSL layer needs to be done by the application or at least outside of libcurl. The exact procedure how to do SSL initialization depends on the TLS backend libcurl uses. Doing TLS based transfers without having the TLS layer initialized may lead to unexpected behaviors. .IP CURL_GLOBAL_WIN32 Initialize the Win32 socket libraries. The implication here is that if this bit is not set, the initialization of Winsock has to be done by the application or you risk getting undefined behaviors. This option exists for when the initialization is handled outside of libcurl so there is no need for libcurl to do it again. .IP CURL_GLOBAL_NOTHING Initialize nothing extra. This sets no bit. .IP CURL_GLOBAL_DEFAULT A sensible default. It initializes both SSL and Win32. Right now, this equals the functionality of the \fBCURL_GLOBAL_ALL\fP mask. .IP CURL_GLOBAL_ACK_EINTR This bit has no point since 7.69.0 but its behavior is instead the default. Before 7.69.0: when this flag is set, curl acknowledges EINTR condition when connecting or when waiting for data. Otherwise, curl waits until full timeout elapses. (Added in 7.30.0) .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { curl_global_init(CURL_GLOBAL_DEFAULT); /* use libcurl, then before exiting... */ curl_global_cleanup(); } .fi .SH AVAILABILITY Added in curl 7.8 .SH RETURN VALUE If this function returns non\-zero, something went wrong and you cannot use the other curl functions. .SH SEE ALSO .BR curl_easy_init (3), .BR curl_global_cleanup (3), .BR curl_global_init_mem (3), .BR curl_global_sslset (3), .BR curl_global_trace (3), .BR libcurl (3)	3.84 KB	2025-07-08 09:41
📄 curl_global_init_mem.3 .\" generated by cd2nroff 0.1 from curl_global_init_mem.md .TH curl_global_init_mem 3 "2025-06-27" libcurl .SH NAME curl_global_init_mem \- global libcurl initialization with memory callbacks .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_global_init_mem(long flags, curl_malloc_callback m, curl_free_callback f, curl_realloc_callback r, curl_strdup_callback s, curl_calloc_callback c); .fi .SH DESCRIPTION This function works exactly as \fIcurl_global_init(3)\fP with one addition: it allows the application to set callbacks to replace the otherwise used internal memory functions. If you are using libcurl from multiple threads or libcurl was built with the threaded resolver option then the callback functions must be thread safe. The threaded resolver is a common build option to enable (and in some cases the default) so we strongly urge you to make your callback functions thread safe. All callback arguments must be set to valid function pointers. The prototypes for the given callbacks must match these: .IP "void malloc_callback(size_t size);" To replace malloc() .IP "void free_callback(void ptr);" To replace free() .IP "void realloc_callback(void ptr, size_t size);" To replace realloc() .IP "char strdup_callback(const char str);" To replace strdup() .IP "void calloc_callback(size_t nmemb, size_t size);" To replace calloc() This function is otherwise the same as \fIcurl_global_init(3)\fP, please refer to that man page for documentation. .SH CAUTION Manipulating these gives considerable powers to the application to severely screw things up for libcurl. Take care. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf extern void malloc_cb(size_t); extern void free_cb(void ); extern void realloc_cb(void , size_t); extern char strdup_cb(const char ); extern void calloc_cb(size_t, size_t); int main(void) { curl_global_init_mem(CURL_GLOBAL_DEFAULT, malloc_cb, free_cb, realloc_cb, strdup_cb, calloc_cb); } .fi .SH AVAILABILITY Added in curl 7.12.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_global_cleanup (3), .BR curl_global_init (3)	2.56 KB	2025-07-08 09:41
📄 curl_global_sslset.3 .\" generated by cd2nroff 0.1 from curl_global_sslset.md .TH curl_global_sslset 3 "2025-06-27" libcurl .SH NAME curl_global_sslset \- select SSL backend to use .SH SYNOPSIS .nf #include <curl/curl.h> CURLsslset curl_global_sslset(curl_sslbackend id, const char name, const curl_ssl_backend *avail); .fi .SH DESCRIPTION This function configures at runtime which SSL backend to use with libcurl. This function can only be used to select an SSL backend once, and it must be called \fBbefore\fP \fIcurl_global_init(3)\fP. The backend can be identified by the \fIid\fP (e.g. \fBCURLSSLBACKEND_OPENSSL\fP). The backend can also be specified via the \fIname\fP parameter for a case insensitive match (passing \fBCURLSSLBACKEND_NONE\fP as \fIid\fP). If both \fIid\fP and \fIname\fP are specified, the \fIname\fP is ignored. If neither \fIid\fP nor \fIname\fP are specified, the function fails with \fBCURLSSLSET_UNKNOWN_BACKEND\fP and set the \fIavail\fP pointer to the NULL\-terminated list of available backends. The available backends are those that this particular build of libcurl supports. Since libcurl 7.60.0, the \fIavail\fP pointer is always set to the list of alternatives if non\-NULL. Upon success, the function returns \fBCURLSSLSET_OK\fP. If the specified SSL backend is not available, the function returns \fBCURLSSLSET_UNKNOWN_BACKEND\fP and sets the \fIavail\fP pointer to a NULL\-terminated list of available SSL backends. In this case, you may call the function again to try to select a different backend. The SSL backend can be set only once. If it has already been set, a subsequent attempt to change it results in a \fBCURLSSLSET_TOO_LATE\fP getting returned. This function is thread\-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set (most platforms). If this is not thread\-safe, you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. .SH Names SSL backend names (case\-insensitive): BearSSL, GnuTLS, mbedTLS, OpenSSL, Rustls, Schannel, Secure\-Transport, wolfSSL The name "OpenSSL" is used for all versions of OpenSSL and its associated forks/flavors in this function. OpenSSL, BoringSSL, LibreSSL, quictls and AmiSSL are all supported by libcurl, but in the eyes of \fIcurl_global_sslset(3)\fP they are all just "OpenSSL". They all mostly provide the same API. \fIcurl_version_info(3)\fP can return more specific info about the exact OpenSSL flavor and version number in use. .SH struct .nf typedef struct { curl_sslbackend id; const char name; } curl_ssl_backend; typedef enum { CURLSSLBACKEND_NONE = 0, CURLSSLBACKEND_OPENSSL = 1, /* or one of its forks / CURLSSLBACKEND_GNUTLS = 2, CURLSSLBACKEND_NSS = 3, CURLSSLBACKEND_GSKIT = 5, / deprecated / CURLSSLBACKEND_POLARSSL = 6, / deprecated / CURLSSLBACKEND_WOLFSSL = 7, CURLSSLBACKEND_SCHANNEL = 8, CURLSSLBACKEND_SECURETRANSPORT = 9, CURLSSLBACKEND_AXTLS = 10, / deprecated / CURLSSLBACKEND_MBEDTLS = 11, CURLSSLBACKEND_MESALINK = 12, / deprecated / CURLSSLBACKEND_BEARSSL = 13, CURLSSLBACKEND_RUSTLS = 14 } curl_sslbackend; .fi .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { int i; / choose a specific backend / curl_global_sslset(CURLSSLBACKEND_WOLFSSL, NULL, NULL); / list the available ones / const curl_ssl_backend *list; curl_global_sslset(CURLSSLBACKEND_NONE, NULL, &list); for(i = 0; list[i]; i++) printf("SSL backend #%d: '%s' (ID: %d)\\n", i, list[i]->name, list[i]->id); } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE If this function returns \fICURLSSLSET_OK\fP, the backend was successfully selected. If the chosen backend is unknown (or support for the chosen backend has not been compiled into libcurl), the function returns \fICURLSSLSET_UNKNOWN_BACKEND\fP. If the backend had been configured previously, or if \fIcurl_global_init(3)\fP has already been called, the function returns \fICURLSSLSET_TOO_LATE\fP. If this libcurl was built completely without SSL support, with no backends at all, this function returns \fICURLSSLSET_NO_BACKENDS\fP. .SH SEE ALSO .BR curl_global_init (3), .BR libcurl (3)	4.29 KB	2025-07-08 09:41
📄 curl_global_trace.3 .\" generated by cd2nroff 0.1 from curl_global_trace.md .TH curl_global_trace 3 "2025-06-27" libcurl .SH NAME curl_global_trace \- log configuration .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_global_trace(const char config); .fi .SH DESCRIPTION This function configures the logging behavior to make some parts of curl more verbose or silent than others. This function may be called during the initialization phase of a program. It does not have to be. It can be called several times even, possibly overwriting settings of previous calls. Calling this function after transfers have been started is undefined. On some platforms/architectures it might take effect, on others not. This function is thread\-safe since libcurl 8.3.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set (most platforms). If this is not thread\-safe, you must not call this function when any other thread in the program (i.e. a thread sharing the same memory) is running. This does not just mean no other thread that is using libcurl. Because \fIcurl_global_init(3)\fP may call functions of other libraries that are similarly thread unsafe, it could conflict with any other thread that uses these other libraries. If you are initializing libcurl from a Windows DLL you should not initialize it from \fIDllMain\fP or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock. The \fIconfig\fP string is a list of comma\-separated component names. Names are case\-insensitive and unknown names are ignored. The special name "all" applies to all components. Names may be prefixed with \(aq+\(aq or \(aq\-\(aq to enable or disable detailed logging for a component. The list of component names is not part of curl\(aqs public API. Names may be added or disappear in future versions of libcurl. Since unknown names are silently ignored, outdated log configurations does not cause errors when upgrading libcurl. Given that, some names can be expected to be fairly stable and are listed below for easy reference. Note that log configuration applies only to transfers where debug logging is enabled. See \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP on how to control that. .SH TRACE COMPONENTS .IP tcp Tracing of TCP socket handling: connect, sends, receives. .IP ssl Tracing of SSL/TLS operations, whichever SSL backend is used in your build. .IP ftp Tracing of FTP operations when this protocol is enabled in your build. .IP http/2 Details about HTTP/2 handling: frames, events, I/O, etc. .IP http/3 Details about HTTP/3 handling: connect, frames, events, I/O etc. .IP http-proxy Involved when transfers are tunneled through an HTTP proxy. "h1\-proxy" or \&"h2\-proxy" are also involved, depending on the HTTP version negotiated with the proxy. In order to find out all components involved in a transfer, run it with "all" configured. You can then see all names involved in your libcurl version in the trace. .IP dns Tracing of DNS operations to resolve hostnames and HTTPS records. .IP lib-ids Adds transfer and connection identifiers as prefix to every call to \fICURLOPT_DEBUGFUNCTION(3)\fP. The format is \fI[n\-m]\fP where \fIn\fP is the identifier of the transfer and \fIm\fP is the identifier of the connection. A literal \fIx\fP is used for internal transfers or when no connection is assigned. For example, \fI[5\-x]\fP is the prefix for transfer 5 that has no connection. The command line tool \fIcurl\fPuses the same format for its \fI\--trace\-ids\fP option. \fIlib\-ids\fP is intended for libcurl applications that handle multiple transfers but have no own way to identify in trace output which transfer a trace event is connected to. .IP doh Former name for DNS\-over\-HTTP operations. Now an alias for \fIdns\fP. .IP multi Traces multi operations managing transfers\(aq state changes and sockets poll states. .IP read Traces reading of upload data from the application in order to send it to the server. .IP ssls Tracing of SSL Session handling, e.g. caching/import/export. .IP smtp Tracing of SMTP operations when this protocol is enabled in your build. .IP write Traces writing of download data, received from the server, to the application. .IP ws Tracing of WebSocket operations when this protocol is enabled in your build. .SH TRACE GROUPS Besides the specific component names there are the following group names defined: .IP all .IP network All components involved in bare network I/O, including the SSL layer. All components that your libcurl is built with. .IP protocol All components involved in transfer protocols, such as \(aqftp\(aq and \(aqhttp/2\(aq. .IP proxy All components involved in use of proxies. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { / log details of HTTP/2 and SSL handling / curl_global_trace("http/2,ssl"); / log all details, except SSL handling / curl_global_trace("all,-ssl"); } .fi Below is a trace sample where "http/2" was configured. The trace output of an enabled component appears at the beginning in brackets. .nf [HTTP/2] [h2sid=1] cf_send(len=96) submit https://example.com/ \&... * [HTTP/2] [h2sid=1] FRAME[HEADERS] * [HTTP/2] [h2sid=1] 249 header bytes \&... .fi .SH AVAILABILITY Added in curl 8.3.0 .SH RETURN VALUE If this function returns non\-zero, something went wrong and the configuration may not have any effects or may only been applied partially. .SH SEE ALSO .BR curl_global_init (3), .BR libcurl (3)	5.39 KB	2025-07-08 09:41
📄 curl_mime_addpart.3 .\" generated by cd2nroff 0.1 from curl_mime_addpart.md .TH curl_mime_addpart 3 "2025-06-27" libcurl .SH NAME curl_mime_addpart \- append a new empty part to a mime structure .SH SYNOPSIS .nf #include <curl/curl.h> curl_mimepart curl_mime_addpart(curl_mime mime); .fi .SH DESCRIPTION \fIcurl_mime_addpart(3)\fP creates and appends a new empty part to the given mime structure and returns a handle to it. The returned part handle can subsequently be populated using functions from the mime API. \fImime\fP is the handle of the mime structure in which the new part must be appended. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / continue and set name + data to the part */ curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); curl_mime_name(part, "data"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE A mime part structure handle, or NULL upon failure. .SH SEE ALSO .BR curl_mime_data (3), .BR curl_mime_data_cb (3), .BR curl_mime_encoder (3), .BR curl_mime_filedata (3), .BR curl_mime_filename (3), .BR curl_mime_headers (3), .BR curl_mime_init (3), .BR curl_mime_name (3), .BR curl_mime_subparts (3), .BR curl_mime_type (3)	1.41 KB	2025-07-08 09:41
📄 curl_mime_data.3 .\" generated by cd2nroff 0.1 from curl_mime_data.md .TH curl_mime_data 3 "2025-06-27" libcurl .SH NAME curl_mime_data \- set a mime part\(aqs body data from memory .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_data(curl_mimepart part, const char data, size_t datasize); .fi .SH DESCRIPTION \fIcurl_mime_data(3)\fP sets a mime part\(aqs body content from memory data. \fIpart\fP is the mime part to assign contents to, created with \fIcurl_mime_addpart(3)\fP. \fIdata\fP points to the data that gets copied by this function. The storage may safely be reused after the call. \fIdatasize\fP is the number of bytes \fIdata\fP points to. It can be set to \fICURL_ZERO_TERMINATED\fP to indicate \fIdata\fP is a null\-terminated character string. Setting a part\(aqs contents multiple times is valid: only the value set by the last call is retained. It is possible to unassign part\(aqs contents by setting \fIdata\fP to NULL. Setting large data is memory consuming: one might consider using \fIcurl_mime_data_cb(3)\fP in such a case. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / add data to the part */ curl_mime_data(part, "raw contents to send", CURL_ZERO_TERMINATED); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_data_cb (3), .BR curl_mime_name (3), .BR curl_mime_type (3)	1.94 KB	2025-07-08 09:41
📄 curl_mime_data_cb.3 .\" generated by cd2nroff 0.1 from curl_mime_data_cb.md .TH curl_mime_data_cb 3 "2025-06-27" libcurl .SH NAME curl_mime_data_cb \- set a callback\-based data source for a mime part\(aqs body .SH SYNOPSIS .nf #include <curl/curl.h> size_t readfunc(char buffer, size_t size, size_t nitems, void arg); int seekfunc(void arg, curl_off_t offset, int origin); void freefunc(void arg); CURLcode curl_mime_data_cb(curl_mimepart part, curl_off_t datasize, curl_read_callback readfunc, curl_seek_callback seekfunc, curl_free_callback freefunc, void arg); .fi .SH DESCRIPTION \fIcurl_mime_data_cb(3)\fP sets the data source of a mime part\(aqs body content from a data read callback function. \fIpart\fP is the part\(aqs to assign contents to. \fIreadfunc\fP is a pointer to a data read callback function, with a signature as shown by the above prototype. It may not be set to NULL. \fIseekfunc\fP is a pointer to a seek callback function, with a signature as shown by the above prototype. This function is used when resending data (i.e.: after a redirect); this pointer may be set to NULL, in which case a resend might not be not possible. \fIfreefunc\fP is a pointer to a user resource freeing callback function, with a signature as shown by the above prototype. If no resource is to be freed, it may safely be set to NULL. This function is called upon mime structure freeing. \fIarg\fP is a user defined argument to callback functions. The read callback function gets called by libcurl as soon as it needs to read data in order to send it to the peer \- like if you ask it to upload or post data to the server. The data area pointed at by the pointer \fIbuffer\fP should be filled up with at most \fIsize\fP multiplied with \fInitems\fP number of bytes by your function. Your read function must then return the actual number of bytes that it stored in that memory area. Returning 0 signals end\-of\-file to the library and cause it to stop the current transfer. If you stop the current transfer by returning 0 "pre\-maturely" (i.e. before the server expected it, like when you have said you intend to upload N bytes and yet you upload less than N bytes), you may experience that the server \&"hangs" waiting for the rest of the data that does not come. The read callback may return \fICURL_READFUNC_ABORT\fP to stop the current operation immediately, resulting in a \fICURLE_ABORTED_BY_CALLBACK\fP error code from the transfer. The callback can return \fICURL_READFUNC_PAUSE\fP to cause reading from this connection to pause. See \fIcurl_easy_pause(3)\fP for further details. The seek function gets called by libcurl to rewind input stream data or to seek to a certain position. The function shall work like fseek(3) or lseek(3) and it gets SEEK_SET, SEEK_CUR or SEEK_END as argument for \fIorigin\fP, although libcurl currently only passes SEEK_SET. The callback function must return \fICURL_SEEKFUNC_OK\fP on success, \fICURL_SEEKFUNC_FAIL\fP to cause the upload operation to fail or \fICURL_SEEKFUNC_CANTSEEK\fP to indicate that while the seek failed, libcurl is free to work around the problem if possible. The latter can sometimes be done by instead reading from the input or similar. Care must be taken if the part is bound to a curl easy handle that is later duplicated: the \fIarg\fP pointer argument is also duplicated, resulting in the pointed item to be shared between the original and the copied handle. In particular, special attention should be given to the \fIfreefunc\fP procedure code since it then gets called twice with the same argument. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE Sending a huge data string causes the same amount of memory to be allocated: to avoid overhead resources consumption, one might want to use a callback source to avoid data duplication. In this case, original data must be retained until after the transfer terminates. .nf #include <string.h> /* for memcpy / char hugedata[512000]; struct ctl { char buffer; curl_off_t size; curl_off_t position; }; size_t read_callback(char buffer, size_t size, size_t nitems, void arg) { struct ctl p = (struct ctl ) arg; curl_off_t sz = p->size - p->position; nitems = size; if(sz > nitems) sz = nitems; if(sz) memcpy(buffer, p->buffer + p->position, sz); p->position += sz; return sz; } int seek_callback(void arg, curl_off_t offset, int origin) { struct ctl p = (struct ctl ) arg; switch(origin) { case SEEK_END: offset += p->size; break; case SEEK_CUR: offset += p->position; break; } if(offset < 0) return CURL_SEEKFUNC_FAIL; p->position = offset; return CURL_SEEKFUNC_OK; } int main(void) { CURL curl = curl_easy_init(); if(curl) { curl_mime mime = curl_mime_init(curl); curl_mimepart *part = curl_mime_addpart(mime); struct ctl hugectl; hugectl.buffer = hugedata; hugectl.size = sizeof(hugedata); hugectl.position = 0; curl_mime_data_cb(part, hugectl.size, read_callback, seek_callback, NULL, &hugectl); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_easy_duphandle (3), .BR curl_mime_addpart (3), .BR curl_mime_data (3), .BR curl_mime_name (3)	5.53 KB	2025-07-08 09:41
📄 curl_mime_encoder.3 .\" generated by cd2nroff 0.1 from curl_mime_encoder.md .TH curl_mime_encoder 3 "2025-06-27" libcurl .SH NAME curl_mime_encoder \- set a mime part\(aqs encoder and content transfer encoding .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_encoder(curl_mimepart part, const char encoding); .fi .SH DESCRIPTION curl_mime_encoder() requests a mime part\(aqs content to be encoded before being transmitted. \fIpart\fP is the part\(aqs handle to assign an encoder. \fIencoding\fP is a pointer to a null\-terminated encoding scheme. It may be set to NULL to disable an encoder previously attached to the part. The encoding scheme storage may safely be reused after this function returns. Setting a part\(aqs encoder multiple times is valid: only the value set by the last call is retained. Upon multipart rendering, the part\(aqs content is encoded according to the pertaining scheme and a corresponding \fI"Content\-Transfer\-Encoding"\fP header is added to the part. Supported encoding schemes are: \&"\fIbinary\fP": the data is left unchanged, the header is added. \&"\fI8bit\fP": header added, no data change. \&"\fI7bit\fP": the data is unchanged, but is each byte is checked to be a 7\-bit value; if not, a read error occurs. \&"\fIbase64\fP": Data is converted to base64 encoding, then split in CRLF\-terminated lines of at most 76 characters. \&"\fIquoted\-printable\fP": data is encoded in quoted printable lines of at most 76 characters. Since the resulting size of the final data cannot be determined prior to reading the original data, it is left as unknown, causing chunked transfer in HTTP. For the same reason, this encoder may not be used with IMAP. This encoder targets text data that is mostly ASCII and should not be used with other types of data. If the original data is already encoded in such a scheme, a custom \fIContent\-Transfer\-Encoding\fP header should be added with \fIcurl_mime_headers(3)\fP instead of setting a part encoder. Encoding should not be applied to multiparts, thus the use of this function on a part with content set with \fIcurl_mime_subparts(3)\fP is strongly discouraged. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / send a file / curl_mime_filedata(part, "image.png"); / encode file data in base64 for transfer */ curl_mime_encoder(part, "base64"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_headers (3), .BR curl_mime_subparts (3)	3.01 KB	2025-07-08 09:41
📄 curl_mime_filedata.3 .\" generated by cd2nroff 0.1 from curl_mime_filedata.md .TH curl_mime_filedata 3 "2025-06-27" libcurl .SH NAME curl_mime_filedata \- set a mime part\(aqs body data from a file contents .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_filedata(curl_mimepart part, const char filename); .fi .SH DESCRIPTION \fIcurl_mime_filedata(3)\fP sets a mime part\(aqs body content from the named file\(aqs contents. This is an alternative to \fIcurl_mime_data(3)\fP for setting data to a mime part. \fIpart\fP is the part\(aqs to assign contents to. \fIfilename\fP points to the null\-terminated file\(aqs path name. The pointer can be NULL to detach the previous part contents settings. Filename storage can be safely be reused after this call. As a side effect, the part\(aqs remote filename is set to the base name of the given \fIfilename\fP if it is a valid named file. This can be undone or overridden by a subsequent call to \fIcurl_mime_filename(3)\fP. The contents of the file is read during the file transfer in a streaming manner to allow huge files to get transferred without using much memory. It therefore requires that the file is kept intact during the entire request. If the file size cannot be determined before actually reading it (such as for a character device or named pipe), the whole mime structure containing the part is transferred using chunks by HTTP but is rejected by IMAP. Setting a part\(aqs contents multiple times is valid: only the value set by the last call is retained. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / send data from this file / curl_mime_filedata(part, "image.png"); / set name */ curl_mime_name(part, "data"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. CURLE_READ_ERROR is only an indication that the file is not yet readable: it can be safely ignored at this time, but the file must be made readable before the pertaining easy handle is performed. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_data (3), .BR curl_mime_filename (3), .BR curl_mime_name (3)	2.62 KB	2025-07-08 09:41
📄 curl_mime_filename.3 .\" generated by cd2nroff 0.1 from curl_mime_filename.md .TH curl_mime_filename 3 "2025-06-27" libcurl .SH NAME curl_mime_filename \- set a mime part\(aqs remote filename .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_filename(curl_mimepart part, const char filename); .fi .SH DESCRIPTION \fIcurl_mime_filename(3)\fP sets a mime part\(aqs remote filename. When remote filename is set, content data is processed as a file, whatever is the part\(aqs content source. A part\(aqs remote filename is transmitted to the server in the associated Content\-Disposition generated header. \fIpart\fP is the part\(aqs handle to assign the remote filename to. \fIfilename\fP points to the null\-terminated filename string; it may be set to NULL to remove a previously attached remote filename. The remote filename string is copied into the part, thus the associated storage may safely be released or reused after call. Setting a part\(aqs file name multiple times is valid: only the value set by the last call is retained. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf static char imagebuf[]="imagedata"; int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / send image data from memory / curl_mime_data(part, imagebuf, sizeof(imagebuf)); / set a file name to make it look like a file upload / curl_mime_filename(part, "image.png"); / set name */ curl_mime_name(part, "data"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_data (3), .BR curl_mime_filedata (3)	2.08 KB	2025-07-08 09:41
📄 curl_mime_free.3 .\" generated by cd2nroff 0.1 from curl_mime_free.md .TH curl_mime_free 3 "2025-06-27" libcurl .SH NAME curl_mime_free \- free a previously built mime structure .SH SYNOPSIS .nf #include <curl/curl.h> void curl_mime_free(curl_mime mime); .fi .SH DESCRIPTION \fIcurl_mime_free(3)\fP is used to clean up data previously built/appended with \fIcurl_mime_addpart(3)\fP and other mime\-handling functions. This must be called when the data has been used, which typically means after \fIcurl_easy_perform(3)\fP has been called. The handle to free is the one you passed to the \fICURLOPT_MIMEPOST(3)\fP option: attached sub part mime structures must not be explicitly freed as they are by the top structure freeing. \fBmime\fP is the handle as returned from a previous call to \fIcurl_mime_init(3)\fP and may be NULL. Passing in a NULL pointer in \fImime\fP makes this function return immediately with no action. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { /* Build the mime message. / curl_mime mime = curl_mime_init(curl); /* send off the transfer / / Free multipart message. */ curl_mime_free(mime); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE None .SH SEE ALSO .BR curl_free (3), .BR curl_mime_init (3)	1.32 KB	2025-07-08 09:41
📄 curl_mime_headers.3 .\" generated by cd2nroff 0.1 from curl_mime_headers.md .TH curl_mime_headers 3 "2025-06-27" libcurl .SH NAME curl_mime_headers \- set a mime part\(aqs custom headers .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_headers(curl_mimepart part, struct curl_slist headers, int take_ownership); .fi .SH DESCRIPTION \fIcurl_mime_headers(3)\fP sets a mime part\(aqs custom headers. \fIpart\fP is the part\(aqs handle to assign the custom headers list to. \fIheaders\fP is the head of a list of custom headers; it may be set to NULL to remove a previously attached custom header list. \fItake_ownership\fP: when non\-zero, causes the list to be freed upon replacement or mime structure deletion; in this case the list must not be freed explicitly. Setting a part\(aqs custom headers list multiple times is valid: only the value set by the last call is retained. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { struct curl_slist headers = NULL; CURL easy = curl_easy_init(); curl_mime mime; curl_mimepart part; headers = curl_slist_append(headers, "Custom-Header: mooo"); mime = curl_mime_init(easy); part = curl_mime_addpart(mime); /* use these headers in the part, takes ownership / curl_mime_headers(part, headers, 1); / pass on this data / curl_mime_data(part, "12345679", CURL_ZERO_TERMINATED); / set name / curl_mime_name(part, "numbers"); / Post and send it. */ curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); curl_easy_perform(easy); } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_name (3)	2.03 KB	2025-07-08 09:41
📄 curl_mime_init.3 .\" generated by cd2nroff 0.1 from curl_mime_init.md .TH curl_mime_init 3 "2025-06-27" libcurl .SH NAME curl_mime_init \- create a mime handle .SH SYNOPSIS .nf #include <curl/curl.h> curl_mime curl_mime_init(CURL easy_handle); .fi .SH DESCRIPTION \fIcurl_mime_init(3)\fP creates a handle to a new empty mime structure. This mime structure can be subsequently filled using the mime API, then attached to some easy handle using option \fICURLOPT_MIMEPOST(3)\fP within a \fIcurl_easy_setopt(3)\fP call or added as a multipart in another mime handle\(aqs part using \fIcurl_mime_subparts(3)\fP. \fIeasy_handle\fP is used for part separator randomization and error reporting. Since 7.87.0, it does not need to be the final target handle. Using a mime handle is the recommended way to post an HTTP form, format and send a multi\-part email with SMTP or upload such an email to an IMAP server. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { CURL easy = curl_easy_init(); curl_mime mime; curl_mimepart part; / Build an HTTP form with a single field named "data", / mime = curl_mime_init(easy); part = curl_mime_addpart(mime); curl_mime_data(part, "This is the field data", CURL_ZERO_TERMINATED); curl_mime_name(part, "data"); / Post and send it. / curl_easy_setopt(easy, CURLOPT_MIMEPOST, mime); curl_easy_setopt(easy, CURLOPT_URL, "https://example.com"); curl_easy_perform(easy); / Clean-up. */ curl_easy_cleanup(easy); curl_mime_free(mime); } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE A mime struct handle, or NULL upon failure. .SH SEE ALSO .BR CURLOPT_MIMEPOST (3), .BR curl_mime_addpart (3), .BR curl_mime_free (3), .BR curl_mime_subparts (3)	1.71 KB	2025-07-08 09:41
📄 curl_mime_name.3 .\" generated by cd2nroff 0.1 from curl_mime_name.md .TH curl_mime_name 3 "2025-06-27" libcurl .SH NAME curl_mime_name \- set a mime part\(aqs name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_name(curl_mimepart part, const char name); .fi .SH DESCRIPTION \fIcurl_mime_name(3)\fP sets a mime part\(aqs name. This is the way HTTP form fields are named. \fIpart\fP is the part\(aqs handle to assign a name to. \fIname\fP points to the null\-terminated name string. The name string is copied into the part, thus the associated storage may safely be released or reused after call. Setting a part\(aqs name multiple times is valid: only the value set by the last call is retained. It is possible to reset the name of a part by setting \fIname\fP to NULL. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / give the part a name */ curl_mime_name(part, "shoe_size"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_data (3), .BR curl_mime_type (3)	1.58 KB	2025-07-08 09:41
📄 curl_mime_subparts.3 .\" generated by cd2nroff 0.1 from curl_mime_subparts.md .TH curl_mime_subparts 3 "2025-06-27" libcurl .SH NAME curl_mime_subparts \- set sub\-parts of a multipart mime part .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_subparts(curl_mimepart part, curl_mime subparts); .fi .SH DESCRIPTION \fIcurl_mime_subparts(3)\fP sets a multipart mime part\(aqs content from a mime structure. \fIpart\fP is a handle to the multipart part. \fIsubparts\fP is a mime structure handle holding the sub\-parts. After \fIcurl_mime_subparts(3)\fP succeeds, the mime structure handle belongs to the multipart part and must not be freed explicitly. It may however be updated by subsequent calls to mime API functions. Setting a part\(aqs contents multiple times is valid: only the value set by the last call is retained. It is possible to unassign previous part\(aqs contents by setting \fIsubparts\fP to NULL. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf static char inline_html = "<title>example</title>"; static char inline_text = "once upon the time"; int main(void) { CURL curl = curl_easy_init(); if(curl) { struct curl_slist slist; /* The inline part is an alternative proposing the html and the text versions of the email. / curl_mime alt = curl_mime_init(curl); curl_mimepart part; / HTML message. / part = curl_mime_addpart(alt); curl_mime_data(part, inline_html, CURL_ZERO_TERMINATED); curl_mime_type(part, "text/html"); / Text message. / part = curl_mime_addpart(alt); curl_mime_data(part, inline_text, CURL_ZERO_TERMINATED); / Create the inline part. */ part = curl_mime_addpart(alt); curl_mime_subparts(part, alt); curl_mime_type(part, "multipart/alternative"); slist = curl_slist_append(NULL, "Content-Disposition: inline"); curl_mime_headers(part, slist, 1); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_init (3)	2.3 KB	2025-07-08 09:41
📄 curl_mime_type.3 .\" generated by cd2nroff 0.1 from curl_mime_type.md .TH curl_mime_type 3 "2025-06-27" libcurl .SH NAME curl_mime_type \- set a mime part\(aqs content type .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_mime_type(curl_mimepart part, const char mimetype); .fi .SH DESCRIPTION \fIcurl_mime_type(3)\fP sets a mime part\(aqs content type. \fIpart\fP is the part\(aqs handle to assign the content type to. \fImimetype\fP points to the null\-terminated file mime type string; it may be set to NULL to remove a previously attached mime type. The mime type string is copied into the part, thus the associated storage may safely be released or reused after call. Setting a part\(aqs type multiple times is valid: only the value set by the last call is retained. In the absence of a mime type and if needed by the protocol specifications, a default mime type is determined by the context: - If set as a custom header, use this value. - application/form\-data for an HTTP form post. - If a remote filename is set, the mime type is taken from the filename extension, or application/octet\-stream by default. - For a multipart part, multipart/mixed. - text/plain in other cases. .SH PROTOCOLS This functionality affects http, imap and smtp .SH EXAMPLE .nf int main(void) { curl_mime mime; curl_mimepart part; CURL curl = curl_easy_init(); if(curl) { / create a mime handle / mime = curl_mime_init(curl); / add a part / part = curl_mime_addpart(mime); / get data from this file / curl_mime_filedata(part, "image.png"); / content-type for this part / curl_mime_type(part, "image/png"); / set name */ curl_mime_name(part, "image"); } } .fi .SH AVAILABILITY Added in curl 7.56.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. .SH SEE ALSO .BR curl_mime_addpart (3), .BR curl_mime_data (3), .BR curl_mime_name (3)	2.12 KB	2025-07-08 09:41
📄 curl_mprintf.3 .\" generated by cd2nroff 0.1 from curl_mprintf.md .TH curl_printf 3 "2025-06-27" libcurl .SH NAME curl_maprintf, curl_mfprintf, curl_mprintf, curl_msnprintf, curl_msprintf, curl_mvaprintf, curl_mvfprintf, curl_mvprintf, curl_mvsnprintf, curl_mvsprintf \- formatted output conversion .SH SYNOPSIS .nf #include <curl/mprintf.h> int curl_mprintf(const char format, ...); int curl_mfprintf(FILE fd, const char format, ...); int curl_msprintf(char buffer, const char format, ...); int curl_msnprintf(char buffer, size_t maxlength, const char format, ...); int curl_mvprintf(const char format, va_list args); int curl_mvfprintf(FILE fd, const char format, va_list args); int curl_mvsprintf(char buffer, const char format, va_list args); int curl_mvsnprintf(char buffer, size_t maxlength, const char format, va_list args); char curl_maprintf(const char format , ...); char curl_mvaprintf(const char format, va_list args); .fi .SH DESCRIPTION These functions produce output according to the format string and given arguments. They are mostly clones of the well\-known C\-style functions but there are slight differences in behavior. We discourage users from using any of these functions in new applications. Functions in the curl_mprintf() family produce output according to a format as described below. The functions \fBcurl_mprintf()\fP and \fBcurl_mvprintf()\fP write output to stdout, the standard output stream; \fBcurl_mfprintf()\fP and \fBcurl_mvfprintf()\fP write output to the given output stream; \fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, \fBcurl_mvsprintf()\fP, and \fBcurl_mvsnprintf()\fP write to the character string \fBbuffer\fP. The functions \fBcurl_msnprintf()\fP and \fBcurl_mvsnprintf()\fP write at most \fImaxlength\fP bytes (including the terminating null byte (\(aq0\(aq)) to \fIbuffer\fP. The functions \fBcurl_mvprintf()\fP, \fBcurl_mvfprintf()\fP, \fBcurl_mvsprintf()\fP, \fBcurl_mvsnprintf()\fP are equivalent to the functions \fBcurl_mprintf()\fP, \fBcurl_mfprintf()\fP, \fBcurl_msprintf()\fP, \fBcurl_msnprintf()\fP, respectively, except that they are called with a \fIva_list\fP instead of a variable number of arguments. These functions do not call the \fIva_end\fP macro. Because they invoke the \fIva_arg\fP macro, the value of \fIap\fP is undefined after the call. The functions \fBcurl_maprintf()\fP and \fBcurl_mvaprintf()\fP return the output string as pointer to a newly allocated memory area. The returned string must be \fIcurl_free(3)\fPed by the receiver. All of these functions write the output under the control of a format string that specifies how subsequent arguments are converted for output. .SH FORMAT STRING The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more \fIflags\fP, an optional minimum \fIfield width\fP, an optional \fIprecision\fP and an optional \fIlength modifier\fP. .SH The $ modifier The arguments must correspond properly with the conversion specifier. By default, the arguments are used in the order given, where each \(aq\(aq (see Field width and Precision below) and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). One can also specify explicitly which argument is taken, at each place where an argument is required, by writing "%m$" instead of \(aq%\(aq and "m$" instead of \(aq\(aq, where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting from 1. Thus, .nf curl_mprintf("%d", width, num); .fi and .nf curl_mprintf("%2$1$d", width, num); .fi are equivalent. The second style allows repeated references to the same argument. If the style using \(aq$\(aq is used, it must be used throughout for all conversions taking an argument and all width and precision arguments, but it may be mixed with "%%" formats, which do not consume an argument. There may be no gaps in the numbers of arguments specified using \(aq$\(aq; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string. .SH Flag characters The character % is followed by zero or more of the following flags: .IP # The value should be converted to its "alternate form". .IP 0 The value should be zero padded. .IP - The converted value is to be left adjusted on the field boundary. (The default is right justification.) The converted value is padded on the right with blanks, rather than on the left with blanks or zeros. A \(aq\-\(aq overrides a &\(aq0\(aq if both are given. .IP (space) (a space: \(aq \(aq) A blank should be left before a positive number (or empty string) produced by a signed conversion. .IP + A sign (+ or \-) should always be placed before a number produced by a signed conversion. By default, a sign is used only for negative numbers. A \(aq+\(aq overrides a space if both are used. .SH Field width An optional decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it gets padded with spaces on the left (or right, if the left\-adjustment flag has been given). Instead of a decimal digit string one may write "\fI" or "\fPm$" (for some decimal integer m) to specify that the field width is given in the next argument, or in the \fIm\-th\fP argument, respectively, which must be of type int. A negative field width is taken as a \(aq\-\(aq flag followed by a positive field width. In no case does a nonexistent or small field width cause truncation of a field; if the result of a conversion is wider than the field width, the field is expanded to contain the conversion result. .SH Precision An optional precision in the form of a period (\(aq.\(aq) followed by an optional decimal digit string. Instead of a decimal digit string one may write "" or \&"m$" (for some decimal integer m) to specify that the precision is given in the next argument, or in the \fIm\-th\fP argument, respectively, which must be of type int. If the precision is given as just \(aq.\(aq, the precision is taken to be zero. A negative precision is taken as if the precision were omitted. This gives the minimum number of digits to appear for \fBd\fP, \fBi\fP, \fBo\fP, \fBu\fP, \fBx\fP, and \fBX\fP conversions, the number of digits to appear after the radix character for \fBa\fP, \fBA\fP, \fBe\fP, \fBE\fP, \fBf\fP, and \fBF\fP conversions, the maximum number of significant digits for \fBg\fP and \fBG\fP conversions, or the maximum number of characters to be printed from a string for \fBs\fP and \fBS\fP conversions. .SH Length modifier .IP h A following integer conversion corresponds to a \fIshort\fP or \fIunsigned short\fP argument. .IP l (ell) A following integer conversion corresponds to a \fIlong\fP or \fIunsigned long\fP argument, or a following n conversion corresponds to a pointer to a long argument .IP ll (ell\-ell). A following integer conversion corresponds to a \fIlong long\fP or \fIunsigned long long\fP argument, or a following n conversion corresponds to a pointer to a \fIlong long\fP argument. .IP q A synonym for \fBll\fP. .IP L A following a, A, e, E, f, F, g, or G conversion corresponds to a long double argument. .IP z A following integer conversion corresponds to a \fIsize_t\fP or \fIssize_t\fP argument. .SH Conversion specifiers A character that specifies the type of conversion to be applied. The conversion specifiers and their meanings are: .IP "d, i" The int argument is converted to signed decimal notation. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. .IP "o, u, x, X" The unsigned int argument is converted to unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal (\fBx\fP and \fBX\fP) notation. The letters \fIabcdef\fP are used for \fBx\fP conversions; the letters \fIABCDEF\fP are used for \fBX\fP conversions. The precision, if any, gives the minimum number of digits that must appear; if the converted value requires fewer digits, it is padded on the left with zeros. The default precision is 1. When 0 is printed with an explicit precision 0, the output is empty. .IP "e, E" The double argument is rounded and output in the style \fB"[\-]d.ddde{+\|\-}dd"\fP .IP "f, F" The double argument is rounded and output to decimal notation in the style \fB"[\-]ddd.ddd"\fP. .IP "g, G" The double argument is converted in style f or e. .IP c The int argument is converted to an unsigned char, and the resulting character is written. .IP s The \fIconst char \fP argument is expected to be a pointer to an array of character type (pointer to a string). Characters from the array are written up to (but not including) a terminating null byte. If a precision is specified, no more than the number specified are written. If a precision is given, no null byte need be present; if the precision is not specified, or is greater than the size of the array, the array must contain a terminating null byte. .IP p The \fIvoid \fP* pointer argument is printed in hexadecimal. .IP n The number of characters written so far is stored into the integer pointed to by the corresponding argument. .IP % A \(aq%\(aq symbol is written. No argument is converted. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf const char *name = "John"; int main(void) { curl_mprintf("My name is %s\\n", name); curl_mprintf("Pi is almost %f\\n", (double)25.0/8); } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE The \fBcurl_maprintf\fP and \fBcurl_mvaprintf\fP functions return a pointer to a newly allocated string, or NULL if it failed. All other functions return the number of characters actually printed (excluding the null byte used to end output to strings). Note that this sometimes differ from how the POSIX versions of these functions work. .SH SEE ALSO .BR fprintf (3), .BR printf (3), .BR sprintf (3), .BR vprintf (3)	10.16 KB	2025-07-08 09:41
📄 curl_multi_add_handle.3 .\" generated by cd2nroff 0.1 from curl_multi_add_handle.md .TH curl_multi_add_handle 3 "2025-06-27" libcurl .SH NAME curl_multi_add_handle \- add an easy handle to a multi session .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_add_handle(CURLM multi_handle, CURL easy_handle); .fi .SH DESCRIPTION Adds the \fIeasy handle\fP to the \fImulti_handle\fP. While an easy handle is added to a multi stack, you cannot and you must not use \fIcurl_easy_perform(3)\fP on that handle. After having removed the easy handle from the multi stack again, it is perfectly fine to use it with the easy interface again. If the easy handle is not set to use a shared (\fICURLOPT_SHARE(3)\fP) cache, it is made to use a DNS cache that is shared between all easy handles within the multi handle when \fIcurl_multi_add_handle(3)\fP is called. When an easy interface is added to a multi handle, it is set to use a shared connection cache owned by the multi handle. Removing and adding new easy handles does not affect the pool of connections or the ability to do connection reuse. If you have \fICURLMOPT_TIMERFUNCTION(3)\fP set in the multi handle (as you should if you are working event\-based with \fIcurl_multi_socket_action(3)\fP and friends), that callback is called from within this function to ask for an updated timer so that your main event loop gets the activity on this handle to get started. The easy handle remains added to the multi handle until you remove it again with \fIcurl_multi_remove_handle(3)\fP \- even when a transfer with that specific easy handle is completed. You should remove the easy handle from the multi stack before you terminate first the easy handle and then the multi handle: 1 \- \fIcurl_multi_remove_handle(3)\fP 2 \- \fIcurl_easy_cleanup(3)\fP 3 \- \fIcurl_multi_cleanup(3)\fP .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { /* init a multi stack / CURLM multi = curl_multi_init(); /* create two easy handles / CURL http_handle = curl_easy_init(); CURL http_handle2 = curl_easy_init(); / add individual transfers */ curl_multi_add_handle(multi, http_handle); curl_multi_add_handle(multi, http_handle2); } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_get_handles (3), .BR curl_multi_init (3), .BR curl_multi_setopt (3), .BR curl_multi_socket_action (3)	2.54 KB	2025-07-08 09:41
📄 curl_multi_assign.3 .\" generated by cd2nroff 0.1 from curl_multi_assign.md .TH curl_multi_assign 3 "2025-06-27" libcurl .SH NAME curl_multi_assign \- set data to associate with an internal socket .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_assign(CURLM multi_handle, curl_socket_t sockfd, void sockptr); .fi .SH DESCRIPTION This function creates an association in the multi handle between the given socket and a private pointer of the application. This is designed for \fIcurl_multi_socket_action(3)\fP uses. When set, the \fIsockptr\fP pointer is passed to all future socket callbacks for the specific \fIsockfd\fP socket. If the given \fIsockfd\fP is not already in use by libcurl, this function returns an error. libcurl only keeps one single pointer associated with a socket, so calling this function several times for the same socket makes the last set pointer get used. The idea here being that this association (socket to private pointer) is something that just about every application that uses this API needs and then libcurl can just as well do it since it already has the necessary functionality. It is acceptable to call this function from your multi callback functions. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM multi = curl_multi_init(); int private = 123; curl_socket_t fd = 0; / file descriptor to associate our data with / / make our struct pointer associated with socket fd */ CURLMcode mc = curl_multi_assign(multi, fd, &private); if(mc) printf("error: %s\\n", curl_multi_strerror(mc)); } .fi .SH TYPICAL USAGE In a typical application you allocate a struct or at least use some kind of semi\-dynamic data for each socket that we must wait for action on when using the \fIcurl_multi_socket_action(3)\fP approach. When our socket\-callback gets called by libcurl and we get to know about yet another socket to wait for, we can use \fIcurl_multi_assign(3)\fP to point out the particular data so that when we get updates about this same socket again, we do not have to find the struct associated with this socket by ourselves. .SH AVAILABILITY Added in curl 7.15.5 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_setopt (3), .BR curl_multi_socket_action (3)	2.4 KB	2025-07-08 09:41
📄 curl_multi_cleanup.3 .\" generated by cd2nroff 0.1 from curl_multi_cleanup.md .TH curl_multi_cleanup 3 "2025-06-27" libcurl .SH NAME curl_multi_cleanup \- close down a multi session .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_cleanup(CURLM multi_handle); .fi .SH DESCRIPTION This function is the opposite of \fIcurl_multi_init(3)\fP. Cleans up and removes a whole multi stack. It does not free or touch any individual easy handles in any way \- they still need to be closed individually, using the usual \fIcurl_easy_cleanup(3)\fP way. The order of cleaning up should be: 1 \- \fIcurl_multi_remove_handle(3)\fP before any easy handles are cleaned up 2 \- \fIcurl_easy_cleanup(3)\fP can now be called independently since the easy handle is no longer connected to the multi handle 3 \- \fIcurl_multi_cleanup(3)\fP should be called when all easy handles are removed When this function is called, remaining entries in the connection pool held by the multi handle are shut down, which might trigger calls to the \fICURLMOPT_SOCKETFUNCTION(3)\fP callback. Passing in a NULL pointer in \fImulti_handle\fP makes this function return CURLM_BAD_HANDLE immediately with no other action. Any use of the \fBmulti_handle\fP after this function has been called and have returned, is illegal. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM multi = curl_multi_init(); /* when the multi transfer is done ... / / remove all easy handles, then: */ curl_multi_cleanup(multi); } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_init (3), .BR curl_multi_get_handles (3), .BR curl_multi_init (3)	1.83 KB	2025-07-08 09:41
📄 curl_multi_fdset.3 .\" generated by cd2nroff 0.1 from curl_multi_fdset.md .TH curl_multi_fdset 3 "2025-06-27" libcurl .SH NAME curl_multi_fdset \- extract file descriptor information from a multi handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_fdset(CURLM multi_handle, fd_set read_fd_set, fd_set write_fd_set, fd_set exc_fd_set, int max_fd); .fi .SH DESCRIPTION This function extracts file descriptor information from a given multi_handle. libcurl returns its \fIfd_set\fP sets. The application can use these to select() on, but be sure to \fIFD_ZERO\fP them before calling this function as \fIcurl_multi_fdset(3)\fP only adds its own descriptors, it does not zero or otherwise remove any others. The \fIcurl_multi_perform(3)\fP function should be called as soon as one of them is ready to be read from or written to. The \fIread_fd_set\fP argument should point to an object of type \fBfd_set\fP that on returns specifies the file descriptors to be checked for being ready to read. The \fIwrite_fd_set\fP argument should point to an object of type \fBfd_set\fP that on return specifies the file descriptors to be checked for being ready to write. The \fIexc_fd_set\fP argument should point to an object of type \fBfd_set\fP that on return specifies the file descriptors to be checked for error conditions. If no file descriptors are set by libcurl, \fImax_fd\fP contain \-1 when this function returns. Otherwise it contains the highest descriptor number libcurl set. When libcurl returns \-1 in \fImax_fd\fP, it is because libcurl currently does something that is not possible for your application to monitor with a socket and unfortunately you can then not know exactly when the current action is completed using select(). You then need to wait a while before you proceed and call \fIcurl_multi_perform(3)\fP anyway. How long to wait? Unless \fIcurl_multi_timeout(3)\fP gives you a lower number, we suggest 100 milliseconds or so, but you may want to test it out in your own particular conditions to find a suitable value. When doing select(), you should use \fIcurl_multi_timeout(3)\fP to figure out how long to wait for action. Call \fIcurl_multi_perform(3)\fP even if no activity has been seen on the \fBfd_sets\fP after the timeout expires as otherwise internal retries and timeouts may not work as you would think and want. If one of the sockets used by libcurl happens to be larger than what can be set in an \fBfd_set\fP, which on POSIX systems means that the file descriptor is larger than \fBFD_SETSIZE\fP, then libcurl tries to not set it. Setting a too large file descriptor in an \fBfd_set\fP implies an out of bounds write which can cause crashes, or worse. The effect of NOT storing it might possibly save you from the crash, but makes your program NOT wait for sockets it should wait for... .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { fd_set fdread; fd_set fdwrite; fd_set fdexcep; int maxfd; int rc; CURLMcode mc; struct timeval timeout = {1, 0}; CURLM multi = curl_multi_init(); do { /* call curl_multi_perform() / FD_ZERO(&fdread); FD_ZERO(&fdwrite); FD_ZERO(&fdexcep); / get file descriptors from the transfers / mc = curl_multi_fdset(multi, &fdread, &fdwrite, &fdexcep, &maxfd); if(mc != CURLM_OK) { fprintf(stderr, "curl_multi_fdset() failed, code %d.\\n", mc); break; } / wait for activity on one of the sockets */ rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); } while(!mc); } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_init (3), .BR curl_multi_perform (3), .BR curl_multi_timeout (3), .BR curl_multi_wait (3), .BR curl_multi_waitfds (3), .BR select (2)	4 KB	2025-07-08 09:41
📄 curl_multi_get_handles.3 .\" generated by cd2nroff 0.1 from curl_multi_get_handles.md .TH curl_multi_get_handles 3 "2025-06-27" libcurl .SH NAME curl_multi_get_handles \- return all added easy handles .SH SYNOPSIS .nf #include <curl/curl.h> CURL *curl_multi_get_handles(CURLM multi_handle); .fi .SH DESCRIPTION Returns an array with pointers to all added easy handles. The end of the list is marked with a NULL pointer. Even if there is not a single easy handle added, this still returns an array but with only a single NULL pointer entry. The returned array contains all the handles that are present at the time of the call. As soon as a handle has been removed from or a handle has been added to the multi handle after the handle array was returned, the two data points are out of sync. The order of the easy handles within the array is not guaranteed. The returned array must be freed with a call to \fIcurl_free(3)\fP after use. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { /* init a multi stack / CURLM multi = curl_multi_init(); CURL curl = curl_easy_init(); if(curl) { / add the transfer / curl_multi_add_handle(multi, curl); / extract all added handles / CURL list = curl_multi_get_handles(multi); if(list) { int i; / remove all added handles */ for(i = 0; list[i]; i++) { curl_multi_remove_handle(multi, list[i]); } curl_free(list); } } } .fi .SH AVAILABILITY Added in curl 8.4.0 .SH RETURN VALUE Returns NULL on failure. Otherwise it returns a pointer to an allocated array. .SH SEE ALSO .BR curl_multi_add_handle (3), .BR curl_multi_cleanup (3), .BR curl_multi_init (3), .BR curl_multi_remove_handle (3)	1.69 KB	2025-07-08 09:41
📄 curl_multi_info_read.3 .\" generated by cd2nroff 0.1 from curl_multi_info_read.md .TH curl_multi_info_read 3 "2025-06-27" libcurl .SH NAME curl_multi_info_read \- read multi stack information .SH SYNOPSIS .nf #include <curl/curl.h> CURLMsg curl_multi_info_read(CURLM multi_handle, int msgs_in_queue); .fi .SH DESCRIPTION Ask the multi handle if there are any messages from the individual transfers. Messages may include information such as an error code from the transfer or just the fact that a transfer is completed. More details on these should be written down as well. Repeated calls to this function returns a new struct each time, until a NULL is returned as a signal that there is no more to get at this point. The integer pointed to with \fImsgs_in_queue\fP contains the number of remaining messages after this function was called. When you fetch a message using this function, it is removed from the internal queue so calling this function again does not return the same message again. It instead returns new messages at each new invoke until the queue is emptied. \fBWARNING:\fP The data the returned pointer points to does not survive calling \fIcurl_multi_cleanup(3)\fP, \fIcurl_multi_remove_handle(3)\fP or \fIcurl_easy_cleanup(3)\fP. The \fICURLMsg\fP struct is simple and only contains basic information. If more involved information is wanted, the particular "easy handle" is present in that struct and can be used in subsequent regular \fIcurl_easy_getinfo(3)\fP calls (or similar): .nf struct CURLMsg { CURLMSG msg; / what this message means / CURL easy_handle; /* the handle it concerns / union { void whatever; /* message-specific data / CURLcode result; / return code for transfer / } data; }; .fi When \fBmsg\fP is \fICURLMSG_DONE\fP, the message identifies a transfer that is done, and then \fBresult\fP contains the return code for the easy handle that just completed. At this point, there are no other \fBmsg\fP types defined. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM multi = curl_multi_init(); CURL curl = curl_easy_init(); if(curl) { struct CURLMsg m; /* call curl_multi_perform or curl_multi_socket_action first, then loop through and check if there are any transfers that have completed / do { int msgq = 0; m = curl_multi_info_read(multi, &msgq); if(m && (m->msg == CURLMSG_DONE)) { CURL e = m->easy_handle; /* m->data.result holds the error code for the transfer */ curl_multi_remove_handle(multi, e); curl_easy_cleanup(e); } } while(m); } } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE A pointer to a filled\-in struct, or NULL if it failed or ran out of structs. It also writes the number of messages left in the queue (after this read) in the integer the second argument points to. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_init (3), .BR curl_multi_perform (3)	2.94 KB	2025-07-08 09:41
📄 curl_multi_init.3 .\" generated by cd2nroff 0.1 from curl_multi_init.md .TH curl_multi_init 3 "2025-06-27" libcurl .SH NAME curl_multi_init \- create a multi handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLM curl_multi_init(); .fi .SH DESCRIPTION This function returns a pointer to a \fICURLM\fP handle to be used as input to all the other multi\-functions, sometimes referred to as a multi handle in some places in the documentation. This init call MUST have a corresponding call to \fIcurl_multi_cleanup(3)\fP when the operation is complete. By default, several caches are stored in and held by the multi handle: DNS cache, connection pool, TLS session ID cache and the TLS CA cert cache. All transfers using the same multi handle share these caches. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { / init a multi stack / CURLM multi = curl_multi_init(); CURL curl = curl_easy_init(); CURL curl2 = curl_easy_init(); /* add individual transfers */ curl_multi_add_handle(multi, curl); curl_multi_add_handle(multi, curl2); } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE If this function returns NULL, something went wrong and you cannot use the other curl functions. .SH SEE ALSO .BR curl_easy_init (3), .BR curl_global_init (3), .BR curl_multi_add_handle (3), .BR curl_multi_cleanup (3), .BR curl_multi_get_handles (3)	1.36 KB	2025-07-08 09:41
📄 curl_multi_perform.3 .\" generated by cd2nroff 0.1 from curl_multi_perform.md .TH curl_multi_perform 3 "2025-06-27" libcurl .SH NAME curl_multi_perform \- run all transfers until it would block .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_perform(CURLM multi_handle, int running_handles); .fi .SH DESCRIPTION This function performs transfers on all the added handles that need attention in a non\-blocking fashion. The easy handles have previously been added to the multi handle with \fIcurl_multi_add_handle(3)\fP. When an application has found out there is data available for the multi_handle or a timeout has elapsed, the application should call this function to read/write whatever there is to read or write right now etc. \fIcurl_multi_perform(3)\fP returns as soon as the reads/writes are done. This function does not require that there actually is any data available for reading or that data can be written, it can be called just in case. It stores the number of handles that still transfer data in the second argument\(aqs integer\-pointer. If the amount of \fIrunning_handles\fP is changed from the previous call (or is less than the amount of easy handles you have added to the multi handle), you know that there is one or more transfers less "running". You can then call \fIcurl_multi_info_read(3)\fP to get information about each individual completed transfer, and that returned info includes CURLcode and more. If an added handle fails quickly, it may never be counted as a running_handle. You could use \fIcurl_multi_info_read(3)\fP to track actual status of the added handles in that case. When \fIrunning_handles\fP is set to zero (0) on the return of this function, there is no longer any transfers in progress. When this function returns error, the state of all transfers are uncertain and they cannot be continued. \fIcurl_multi_perform(3)\fP should not be called again on the same multi handle after an error has been returned, unless first removing all the handles and adding new ones. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { int still_running; CURLM multi = curl_multi_init(); CURL curl = curl_easy_init(); if(curl) { curl_multi_add_handle(multi, curl); do { CURLMcode mc = curl_multi_perform(multi, &still_running); if(!mc && still_running) /* wait for activity, timeout or "nothing" / mc = curl_multi_poll(multi, NULL, 0, 1000, NULL); if(mc) { fprintf(stderr, "curl_multi_poll() failed, code %d.\\n", (int)mc); break; } / if there are still transfers, loop */ } while(still_running); } } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. This function returns errors regarding the whole multi stack. Problems on individual transfers may have occurred even when this function returns \fICURLM_OK\fP. Use \fIcurl_multi_info_read(3)\fP to figure out how individual transfers did. .SH TYPICAL USAGE Most applications use \fIcurl_multi_poll(3)\fP to make libcurl wait for activity on any of the ongoing transfers. As soon as one or more file descriptor has activity or the function times out, the application calls \fIcurl_multi_perform(3)\fP. .SH SEE ALSO .BR curl_multi_add_handle (3), .BR curl_multi_cleanup (3), .BR curl_multi_fdset (3), .BR curl_multi_info_read (3), .BR curl_multi_init (3), .BR curl_multi_wait (3), .BR libcurl-errors (3)	3.5 KB	2025-07-08 09:41
📄 curl_multi_poll.3 .\" generated by cd2nroff 0.1 from curl_multi_poll.md .TH curl_multi_poll 3 "2025-06-27" libcurl .SH NAME curl_multi_poll \- poll on all easy handles in a multi handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_poll(CURLM multi_handle, struct curl_waitfd extra_fds[], unsigned int extra_nfds, int timeout_ms, int numfds); .fi .SH DESCRIPTION \fIcurl_multi_poll(3)\fP polls all file descriptors used by the curl easy handles contained in the given multi handle set. It blocks until activity is detected on at least one of the handles or \fItimeout_ms\fP has passed. Alternatively, if the multi handle has a pending internal timeout that has a shorter expiry time than \fItimeout_ms\fP, that shorter time is used instead to make sure timeout accuracy is reasonably kept. The calling application may pass additional curl_waitfd structures which are similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the same call. On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total number of file descriptors on which interesting events occurred. This number can include both libcurl internal descriptors as well as descriptors provided in \fIextra_fds\fP. The \fIcurl_multi_wakeup(3)\fP function can be used from another thread to wake up this function and return faster. This is one of the details that makes this function different than \fIcurl_multi_wait(3)\fP which cannot be woken up this way. If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function instead waits during \fItimeout_ms\fP milliseconds (or shorter if an internal timer indicates so). This is the other detail that makes this function different than \fIcurl_multi_wait(3)\fP. This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. .SH curl_waitfd .nf struct curl_waitfd { curl_socket_t fd; short events; short revents; }; .fi .IP CURL_WAIT_POLLIN Bit flag to curl_waitfd.events indicating the socket should poll on read events such as new data received. .IP CURL_WAIT_POLLPRI Bit flag to curl_waitfd.events indicating the socket should poll on high priority read events such as out of band data. .IP CURL_WAIT_POLLOUT Bit flag to curl_waitfd.events indicating the socket should poll on write events such as the socket being clear to write without blocking. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf extern void handle_fd(int); int main(void) { CURL easy_handle; CURLM multi_handle; int still_running = 0; int myfd = 2; /* this is our own file descriptor / multi_handle = curl_multi_init(); easy_handle = curl_easy_init(); / add the individual easy handle / curl_multi_add_handle(multi_handle, easy_handle); do { CURLMcode mc; int numfds; mc = curl_multi_perform(multi_handle, &still_running); if(mc == CURLM_OK) { struct curl_waitfd myown; myown.fd = myfd; myown.events = CURL_WAIT_POLLIN; / wait for input / myown.revents = 0; / clear it / / wait for activity on curl's descriptors or on our own, or timeout / mc = curl_multi_poll(multi_handle, &myown, 1, 1000, &numfds); if(myown.revents) { / did our descriptor receive an event? */ handle_fd(myfd); } } if(mc != CURLM_OK) { fprintf(stderr, "curl_multi failed, code %d.\\n", mc); break; } } while(still_running); curl_multi_remove_handle(multi_handle, easy_handle); } .fi .SH AVAILABILITY Added in curl 7.66.0 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_fdset (3), .BR curl_multi_perform (3), .BR curl_multi_wait (3), .BR curl_multi_wakeup (3)	3.99 KB	2025-07-08 09:41
📄 curl_multi_remove_handle.3 .\" generated by cd2nroff 0.1 from curl_multi_remove_handle.md .TH curl_multi_remove_handle 3 "2025-06-27" libcurl .SH NAME curl_multi_remove_handle \- remove an easy handle from a multi session .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_remove_handle(CURLM multi_handle, CURL easy_handle); .fi .SH DESCRIPTION Removes a given \fIeasy_handle\fP from the \fImulti_handle\fP. This makes the specified easy handle be removed from this multi handle\(aqs control. When the easy handle has been removed from a multi stack, it is again perfectly legal to invoke \fIcurl_easy_perform(3)\fP on this easy handle. Removing an easy handle while being in use is perfectly legal and effectively halts the transfer in progress involving that easy handle. All other easy handles and transfers remain unaffected. It is fine to remove a handle at any time during a transfer, just not from within any libcurl callback function. Removing an easy handle from the multi handle before the corresponding transfer is complete might cause libcurl to close the connection \- if the state of it and the internal protocol handler deem it necessary. Otherwise libcurl keeps the connection alive in the connection pool associated with the multi handle, ready to get reused for a future transfer using this multi handle. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLM multi = curl_multi_init(); int queued = 0; / when an easy handle has completed, remove it / CURLMsg msg = curl_multi_info_read(multi, &queued); if(msg) { if(msg->msg == CURLMSG_DONE) { /* a transfer ended */ fprintf(stderr, "Transfer completed\\n"); curl_multi_remove_handle(multi, msg->easy_handle); } } } .fi .SH AVAILABILITY Added in curl 7.9.6 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_add_handle (3), .BR curl_multi_cleanup (3), .BR curl_multi_init (3)	2.04 KB	2025-07-08 09:41
📄 curl_multi_setopt.3 .\" generated by cd2nroff 0.1 from curl_multi_setopt.md .TH curl_multi_setopt 3 "2025-06-27" libcurl .SH NAME curl_multi_setopt \- set options for a curl multi handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM multi, CURLMoption option, parameter); .fi .SH DESCRIPTION \fIcurl_multi_setopt(3)\fP is used to tell a libcurl multi handle how to behave. By using the appropriate options to \fIcurl_multi_setopt(3)\fP, you can change libcurl\(aqs behavior when using that multi handle. All options are set with the \fIoption\fP followed by the \fIparameter\fP. That parameter can be a \fBlong\fP, a \fBfunction pointer\fP, an \fBobject pointer\fP or a \fBcurl_off_t\fP type, depending on what the specific option expects. Read this manual carefully as bad input values may cause libcurl to behave badly. You can only set one option in each function call. .SH OPTIONS .IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE \fBdeprecated\fP See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP .IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE \fBdeprecated\fP See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP .IP CURLMOPT_MAXCONNECTS Size of connection cache. See \fICURLMOPT_MAXCONNECTS(3)\fP .IP CURLMOPT_MAX_CONCURRENT_STREAMS Max concurrent streams for http2. See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP .IP CURLMOPT_MAX_HOST_CONNECTIONS Max number of connections to a single host. See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP .IP CURLMOPT_MAX_PIPELINE_LENGTH \fBdeprecated\fP. See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP .IP CURLMOPT_MAX_TOTAL_CONNECTIONS Max simultaneously open connections. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP .IP CURLMOPT_PIPELINING Enable HTTP multiplexing. See \fICURLMOPT_PIPELINING(3)\fP .IP CURLMOPT_PIPELINING_SERVER_BL \fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP .IP CURLMOPT_PIPELINING_SITE_BL \fBdeprecated\fP. See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP .IP CURLMOPT_PUSHDATA Pointer to pass to push callback. See \fICURLMOPT_PUSHDATA(3)\fP .IP CURLMOPT_PUSHFUNCTION Callback that approves or denies server pushes. See \fICURLMOPT_PUSHFUNCTION(3)\fP .IP CURLMOPT_SOCKETDATA Custom pointer passed to the socket callback. See \fICURLMOPT_SOCKETDATA(3)\fP .IP CURLMOPT_SOCKETFUNCTION Callback informed about what to wait for. See \fICURLMOPT_SOCKETFUNCTION(3)\fP .IP CURLMOPT_TIMERDATA Custom pointer to pass to timer callback. See \fICURLMOPT_TIMERDATA(3)\fP .IP CURLMOPT_TIMERFUNCTION Callback to receive timeout values. See \fICURLMOPT_TIMERFUNCTION(3)\fP .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #define MAX_PARALLEL 45 int main(void) { CURLM multi = curl_multi_init(); /* Limit the amount of simultaneous connections curl should allow: */ curl_multi_setopt(multi, CURLMOPT_MAXCONNECTS, (long)MAX_PARALLEL); } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. Note that it returns a CURLM_UNKNOWN_OPTION if you try setting an option that this version of libcurl does not know of. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_info_read (3), .BR curl_multi_init (3), .BR curl_multi_socket (3)	3.21 KB	2025-07-08 09:41
📄 curl_multi_socket.3 .\" generated by cd2nroff 0.1 from curl_multi_socket.md .TH curl_multi_socket 3 "2025-06-27" libcurl .SH NAME curl_multi_socket \- read/write available data .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_socket(CURLM multi_handle, curl_socket_t sockfd, int running_handles); .fi .SH DESCRIPTION This function is deprecated. Use \fIcurl_multi_socket_action(3)\fP instead with \fBev_bitmask\fP set to 0. At return, the integer \fBrunning_handles\fP points to contains the number of still running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. Note that when you call \fIcurl_multi_socket(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. The \fIcurl_multi_socket(3)\fP functions inform the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time the callback was called. Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option with \fIcurl_multi_setopt(3)\fP. Your application then gets called with information on how long to wait for socket actions at most before doing the timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but for an event\-based system using the callback is far better than relying on polling the timeout value. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { /* the event-library gets told when there activity on the socket 'fd', which we translate to a call to curl_multi_socket_action() / int running; int rc; int fd = 2; CURLM multi = curl_multi_init(); rc = curl_multi_socket(multi, fd, &running); } .fi .SH DEPRECATED \fIcurl_multi_socket(3)\fP is deprecated, use \fIcurl_multi_socket_action(3)\fP instead. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. The return code is for the whole multi stack. Problems still might have occurred on individual transfers even when one of these functions return OK. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_fdset (3), .BR curl_multi_info_read (3), .BR curl_multi_init (3), .BR the hiperfifo.c example	2.75 KB	2025-07-08 09:41
📄 curl_multi_socket_action.3 .\" generated by cd2nroff 0.1 from curl_multi_socket_action.md .TH curl_multi_socket_action 3 "2025-06-27" libcurl .SH NAME curl_multi_socket_action \- read/write available data given an action .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_socket_action(CURLM multi_handle, curl_socket_t sockfd, int ev_bitmask, int running_handles); .fi .SH DESCRIPTION When the application has detected action on a socket handled by libcurl, it should call \fIcurl_multi_socket_action(3)\fP with the \fBsockfd\fP argument set to the socket with the action. When the events on a socket are known, they can be passed as an events bitmask \fBev_bitmask\fP by first setting \fBev_bitmask\fP to 0, and then adding using bitwise OR (\|) any combination of events to be chosen from CURL_CSELECT_IN, CURL_CSELECT_OUT or CURL_CSELECT_ERR. When the events on a socket are unknown, pass 0 instead, and libcurl tests the descriptor internally. It is also permissible to pass CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the whole process or when a timeout occurs. At return, \fBrunning_handles\fP points to the number of running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific socket and the counter decreases by one, it DOES NOT necessarily mean that this exact socket/transfer is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. The \fIcurl_multi_socket_action(3)\fP function informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They update the status with changes since the previous time the callback was called. Get the timeout time by setting the \fICURLMOPT_TIMERFUNCTION(3)\fP option with \fIcurl_multi_setopt(3)\fP. Your application then gets called with information on how long to wait for socket actions at most before doing the timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT. You can also use the \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but for an event\-based system using the callback is far better than relying on polling the timeout value. When this function returns error, the state of all transfers are uncertain and they cannot be continued. \fIcurl_multi_socket_action(3)\fP should not be called again on the same multi handle after an error has been returned, unless first removing all the handles and adding new ones. .SH TYPICAL USAGE 1. Create a multi handle 2. Set the socket callback with \fICURLMOPT_SOCKETFUNCTION(3)\fP 3. Set the timeout callback with \fICURLMOPT_TIMERFUNCTION(3)\fP, to get to know what timeout value to use when waiting for socket activities. 4. Add easy handles with curl_multi_add_handle() 5. Provide some means to manage the sockets libcurl is using, so you can check them for activity. This can be done through your application code, or by way of an external library such as libevent or glib. 6. Call curl_multi_socket_action(..., CURL_SOCKET_TIMEOUT, 0, ...) to kickstart everything. To get one or more callbacks called. 7. Wait for activity on any of libcurl\(aqs sockets, use the timeout value your callback has been told. 8, When activity is detected, call curl_multi_socket_action() for the socket(s) that got action. If no activity is detected and the timeout expires, call \fIcurl_multi_socket_action(3)\fP with \fICURL_SOCKET_TIMEOUT\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { /* the event-library gets told when there activity on the socket 'fd', which we translate to a call to curl_multi_socket_action() / int running = 0; int fd = 3; / the descriptor that had action / int bitmask = 2; / what activity that happened / CURLM multi = curl_multi_init(); CURLMcode mc = curl_multi_socket_action(multi, fd, bitmask, &running); if(mc) printf("error: %s\\n", curl_multi_strerror(mc)); } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_fdset (3), .BR curl_multi_info_read (3), .BR curl_multi_init (3), .BR the hiperfifo.c example	4.59 KB	2025-07-08 09:41
📄 curl_multi_socket_all.3 .\" generated by cd2nroff 0.1 from curl_multi_socket_all.md .TH curl_multi_socket_all 3 "2025-06-27" libcurl .SH NAME curl_multi_socket_all \- reads/writes available data for all easy handles .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_socket_all(CURLM multi_handle, int running_handles); .fi .SH DESCRIPTION This function is deprecated for performance reasons but there are no plans to remove it from the API. Use \fIcurl_multi_socket_action(3)\fP instead. At return, the integer \fBrunning_handles\fP points to contains the number of still running easy handles within the multi handle. When this number reaches zero, all transfers are complete/done. Force libcurl to (re\-)check all its internal sockets and transfers instead of just a single one by calling \fIcurl_multi_socket_all(3)\fP. Note that there should not be any reason to use this function. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { int running; int rc; CURLM *multi = curl_multi_init(); rc = curl_multi_socket_all(multi, &running); } .fi .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. The return code is for the whole multi stack. Problems still might have occurred on individual transfers even when one of these functions return OK. .SH SEE ALSO .BR curl_multi_cleanup (3), .BR curl_multi_fdset (3), .BR curl_multi_info_read (3), .BR curl_multi_init (3), .BR the hiperfifo.c example	1.61 KB	2025-07-08 09:41
📄 curl_multi_strerror.3 .\" generated by cd2nroff 0.1 from curl_multi_strerror.md .TH curl_multi_strerror 3 "2025-06-27" libcurl .SH NAME curl_multi_strerror \- return string describing error code .SH SYNOPSIS .nf #include <curl/curl.h> const char curl_multi_strerror(CURLMcode errornum); .fi .SH DESCRIPTION This function returns a string describing the \fICURLMcode\fP error code passed in the argument \fIerrornum\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { int still_running; CURLM multi = curl_multi_init(); CURLMcode mc = curl_multi_perform(multi, &still_running); if(mc) printf("error: %s\\n", curl_multi_strerror(mc)); } .fi .SH AVAILABILITY Added in curl 7.12.0 .SH RETURN VALUE A pointer to a null\-terminated string. .SH SEE ALSO .BR curl_easy_strerror (3), .BR curl_share_strerror (3), .BR curl_url_strerror (3), .BR libcurl-errors (3)	898 B	2025-07-08 09:41
📄 curl_multi_timeout.3 .\" generated by cd2nroff 0.1 from curl_multi_timeout.md .TH curl_multi_timeout 3 "2025-06-27" libcurl .SH NAME curl_multi_timeout \- how long to wait for action before proceeding .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_timeout(CURLM multi_handle, long timeout); .fi .SH DESCRIPTION An application using the libcurl multi interface should call \fIcurl_multi_timeout(3)\fP to figure out how long it should wait for socket actions \- at most \- before proceeding. Proceeding means either doing the socket\-style timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fBsockfd\fP argument set to CURL_SOCKET_TIMEOUT, or call \fIcurl_multi_perform(3)\fP if you are using the simpler and older multi interface approach. The timeout value returned in the long \fBtimeout\fP points to, is in number of milliseconds at this moment. If 0, it means you should proceed immediately without waiting for anything. If it returns \-1, there is no timeout at all set. An application that uses the \fImulti_socket\fP API should not use this function. It should instead use the \fICURLMOPT_TIMERFUNCTION(3)\fP option for proper and desired behavior. Note: if libcurl returns a \-1 timeout here, it just means that libcurl currently has no stored timeout value. You must not wait too long (more than a few seconds perhaps) before you call \fIcurl_multi_perform(3)\fP again. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { struct timeval timeout; long timeo; fd_set fdread; fd_set fdwrite; fd_set fdexcep; int maxfd = 2; CURLM multi = curl_multi_init(); curl_multi_timeout(multi, &timeo); if(timeo < 0) / no set timeout, use a default / timeo = 980; timeout.tv_sec = timeo / 1000; timeout.tv_usec = (timeo % 1000) 1000; /* wait for activities no longer than the set timeout */ select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout); } .fi .SH TYPICAL USAGE Call \fIcurl_multi_timeout(3)\fP, then wait for action on the sockets. Figure out which sockets to wait for by calling \fIcurl_multi_fdset(3)\fP. When there is activity or timeout, call \fIcurl_multi_perform(3)\fP and then loop \- until all transfers are complete. .SH AVAILABILITY Added in curl 7.15.4 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_fdset (3), .BR curl_multi_info_read (3), .BR curl_multi_setopt (3), .BR curl_multi_socket (3)	2.53 KB	2025-07-08 09:41
📄 curl_multi_wait.3 .\" generated by cd2nroff 0.1 from curl_multi_wait.md .TH curl_multi_wait 3 "2025-06-27" libcurl .SH NAME curl_multi_wait \- poll on all easy handles in a multi handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_wait(CURLM multi_handle, struct curl_waitfd extra_fds[], unsigned int extra_nfds, int timeout_ms, int numfds); .fi .SH DESCRIPTION \fIcurl_multi_wait(3)\fP polls all file descriptors used by the curl easy handles contained in the given multi handle set. It blocks until activity is detected on at least one of the handles or \fItimeout_ms\fP has passed. Alternatively, if the multi handle has a pending internal timeout that has a shorter expiry time than \fItimeout_ms\fP, that shorter time is being used instead to make sure timeout accuracy is reasonably kept. The calling application may pass additional \fIcurl_waitfd\fP structures which are similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure to be waited on in the same call. On completion, if \fInumfds\fP is non\-NULL, it gets populated with the total number of file descriptors on which interesting events occurred. This number can include both libcurl internal descriptors as well as descriptors provided in \fIextra_fds\fP. If no extra file descriptors are provided and libcurl has no file descriptor to offer to wait for, this function returns immediately. (Consider using \fIcurl_multi_poll(3)\fP to avoid this behavior.) This function is encouraged to be used instead of select(3) when using the multi interface to allow applications to easier circumvent the common problem with 1024 maximum file descriptors. .SH curl_waitfd .nf struct curl_waitfd { curl_socket_t fd; short events; short revents; }; .fi .IP CURL_WAIT_POLLIN Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on read events such as new data received. .IP CURL_WAIT_POLLPRI Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on high priority read events such as out of band data. .IP CURL_WAIT_POLLOUT Bit flag to \fIcurl_waitfd.events\fP indicating the socket should poll on write events such as the socket being clear to write without blocking. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL easy; CURLM multi = curl_multi_init(); int still_running; easy = curl_easy_init(); /* add the individual easy handle / curl_multi_add_handle(multi, easy); do { CURLMcode mc; int numfds; mc = curl_multi_perform(multi, &still_running); if(mc == CURLM_OK) { / wait for activity, timeout or "nothing" */ mc = curl_multi_wait(multi, NULL, 0, 1000, &numfds); } if(mc != CURLM_OK) { fprintf(stderr, "curl_multi failed, code %d.\\n", mc); break; } } while(still_running); curl_multi_remove_handle(multi, easy); } .fi .SH AVAILABILITY Added in curl 7.28.0 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_fdset (3), .BR curl_multi_perform (3), .BR curl_multi_poll (3)	3.2 KB	2025-07-08 09:41
📄 curl_multi_waitfds.3 .\" generated by cd2nroff 0.1 from curl_multi_waitfds.md .TH curl_multi_waitfds 3 "2025-06-27" libcurl .SH NAME curl_multi_waitfds \- extract file descriptor information from a multi handle .SH SYNOPSIS .nf #include <curl/curl.h> #include <stdlib.h> CURLMcode curl_multi_waitfds(CURLM multi, struct curl_waitfd ufds, unsigned int size, unsigned int fd_count); .fi .SH DESCRIPTION This function extracts \fIcurl_waitfd\fP structures which are similar to \fIpoll(2)\fP\(aqs \fIpollfd\fP structure from a given multi_handle. These structures can be used for polling on multi_handle file descriptors in a fashion similar to \fIcurl_multi_poll(3)\fP. The \fIcurl_multi_perform(3)\fP function should be called as soon as one of them is ready to be read from or written to. libcurl fills provided \fIufds\fP array up to the \fIsize\fP. If a number of descriptors used by the multi_handle is greater than the \fIsize\fP parameter then libcurl returns CURLM_OUT_OF_MEMORY error. If the \fIfd_count\fP argument is not a null pointer, it points to a variable that on return specifies the number of descriptors used by the multi_handle to be checked for being ready to read or write. The client code can pass \fIsize\fP equal to zero just to get the number of the descriptors and allocate appropriate storage for them to be used in a subsequent function call. In this case, \fIfd_count\fP receives a number greater than or equal to the number of descriptors. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf #include <stdlib.h> int main(void) { CURLMcode mc; struct curl_waitfd ufds; CURLM multi = curl_multi_init(); do { / call curl_multi_perform() / / get the count of file descriptors from the transfers / unsigned int fd_count = 0; mc = curl_multi_waitfds(multi, NULL, 0, &fd_count); if(mc != CURLM_OK) { fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc); break; } if(!fd_count) continue; / no descriptors yet / / allocate storage for our descriptors / ufds = malloc(fd_count sizeof(struct curl_waitfd)); /* get wait descriptors from the transfers and put them into array. / mc = curl_multi_waitfds(multi, ufds, fd_count, &fd_count); if(mc != CURLM_OK) { fprintf(stderr, "curl_multi_waitfds() failed, code %d.\\n", mc); free(ufds); break; } / Do polling on descriptors in ufds */ free(ufds); } while(!mc); } .fi .SH AVAILABILITY Added in curl 8.8.0 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_fdset (3), .BR curl_multi_perform (3), .BR curl_multi_poll (3), .BR curl_multi_wait (3)	2.85 KB	2025-07-08 09:41
📄 curl_multi_wakeup.3 .\" generated by cd2nroff 0.1 from curl_multi_wakeup.md .TH curl_multi_wakeup 3 "2025-06-27" libcurl .SH NAME curl_multi_wakeup \- wake up a sleeping curl_multi_poll call .SH SYNOPSIS .nf #include <curl/curl.h> CURLMcode curl_multi_wakeup(CURLM multi_handle); .fi .SH DESCRIPTION This function can be called from any thread and it wakes up a sleeping \fIcurl_multi_poll(3)\fP call that is currently (or is about to be) waiting for activity or a timeout. If the function is called when there is no \fIcurl_multi_poll(3)\fP call, it causes the next call to return immediately. Calling this function only guarantees to wake up the current (or the next if there is no current) \fIcurl_multi_poll(3)\fP call, which means it is possible that multiple calls to this function wake up the same waiting operation. This function has no effect on \fIcurl_multi_wait(3)\fP calls. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf extern int time_to_die(void); extern int set_something_to_signal_thread_1_to_exit(void); extern int decide_to_stop_thread1(); int main(void) { CURL easy; CURLM multi = curl_multi_init(); int still_running; easy = curl_easy_init(); / add the individual easy handle / curl_multi_add_handle(multi, easy); / this is thread 1 / do { CURLMcode mc; int numfds; mc = curl_multi_perform(multi, &still_running); if(mc == CURLM_OK) { / wait for activity, timeout or wakeup / mc = curl_multi_poll(multi, NULL, 0, 10000, &numfds); } if(time_to_die()) return 1; } while(still_running); curl_multi_remove_handle(multi, easy); / this is thread 2 */ if(decide_to_stop_thread1()) { set_something_to_signal_thread_1_to_exit(); curl_multi_wakeup(multi); } } .fi .SH AVAILABILITY Added in curl 7.68.0 .SH RETURN VALUE This function returns a CURLMcode indicating success or error. CURLM_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. .SH SEE ALSO .BR curl_multi_poll (3), .BR curl_multi_wait (3)	2.03 KB	2025-07-08 09:41
📄 curl_pushheader_byname.3 .\" generated by cd2nroff 0.1 from curl_pushheader_byname.md .TH curl_pushheader_byname 3 "2025-06-27" libcurl .SH NAME curl_pushheader_byname \- get a push header by name .SH SYNOPSIS .nf #include <curl/curl.h> char curl_pushheader_byname(struct curl_pushheaders h, const char name); .fi .SH DESCRIPTION This is a function that is only functional within a \fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it elsewhere and it has no function then. It returns the value for the given header field name (or NULL) for the incoming server push request. This is a shortcut so that the application does not have to loop through all headers to find the one it is interested in. The data this function points to is freed when this callback returns. If more than one header field use the same name, this returns only the first one. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf #include <string.h> / for strncmp / static int push_cb(CURL parent, CURL easy, size_t num_headers, struct curl_pushheaders headers, void clientp) { char headp; int transfers = (int )clientp; FILE out; headp = curl_pushheader_byname(headers, ":path"); if(headp && !strncmp(headp, "/push-", 6)) { fprintf(stderr, "The PATH is %s\\n", headp); / save the push here / out = fopen("pushed-stream", "wb"); / write to this file / curl_easy_setopt(easy, CURLOPT_WRITEDATA, out); (transfers)++; /* one more / return CURL_PUSH_OK; } return CURL_PUSH_DENY; } int main(void) { int counter; CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter); } .fi .SH AVAILABILITY Added in curl 7.44.0 .SH RETURN VALUE Returns a pointer to the header field content or NULL. .SH SEE ALSO .BR CURLMOPT_PUSHFUNCTION (3), .BR curl_pushheader_bynum (3)	1.93 KB	2025-07-08 09:41
📄 curl_pushheader_bynum.3 .\" generated by cd2nroff 0.1 from curl_pushheader_bynum.md .TH curl_pushheader_bynum 3 "2025-06-27" libcurl .SH NAME curl_pushheader_bynum \- get a push header by index .SH SYNOPSIS .nf #include <curl/curl.h> char curl_pushheader_bynum(struct curl_pushheaders h, size_t num); .fi .SH DESCRIPTION This is a function that is only functional within a \fICURLMOPT_PUSHFUNCTION(3)\fP callback. It makes no sense to try to use it elsewhere and it has no function then. It returns the value for the header field at the given index \fBnum\fP, for the incoming server push request or NULL. The data pointed to is freed by libcurl when this callback returns. The returned pointer points to a \&"name:value" string that gets freed when this callback returns. .SH PROTOCOLS This functionality affects http only .SH EXAMPLE .nf /* output all the incoming push request headers / static int push_cb(CURL parent, CURL easy, size_t num_headers, struct curl_pushheaders headers, void clientp) { int i = 0; char field; do { field = curl_pushheader_bynum(headers, i); if(field) fprintf(stderr, "Push header: %s\\n", field); i++; } while(field); return CURL_PUSH_OK; /* permission granted / } int main(void) { CURLM multi = curl_multi_init(); curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_cb); } .fi .SH AVAILABILITY Added in curl 7.44.0 .SH RETURN VALUE Returns a pointer to the header field content or NULL. .SH SEE ALSO .BR CURLMOPT_PUSHFUNCTION (3), .BR curl_pushheader_byname (3)	1.56 KB	2025-07-08 09:41
📄 curl_share_cleanup.3 .\" generated by cd2nroff 0.1 from curl_share_cleanup.md .TH curl_share_cleanup 3 "2025-06-27" libcurl .SH NAME curl_share_cleanup \- close a shared object .SH SYNOPSIS .nf #include <curl/curl.h> CURLSHcode curl_share_cleanup(CURLSH share_handle); .fi .SH DESCRIPTION This function deletes a shared object. The share handle cannot be used anymore when this function has been called. Passing in a NULL pointer in \fIshare_handle\fP makes this function return immediately with no action. Any use of the \fBshare_handle\fP after this function has been called and have returned, is illegal. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); /* use the share, then ... */ curl_share_cleanup(share); } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. If an error occurs, then the share object is not deleted. .SH SEE ALSO .BR curl_share_init (3), .BR curl_share_setopt (3)	1.23 KB	2025-07-08 09:41
📄 curl_share_init.3 .\" generated by cd2nroff 0.1 from curl_share_init.md .TH curl_share_init 3 "2025-06-27" libcurl .SH NAME curl_share_init \- create a share object .SH SYNOPSIS .nf #include <curl/curl.h> CURLSH curl_share_init(); .fi .SH DESCRIPTION This function returns a pointer to a \fICURLSH\fP handle to be used as input to all the other share\-functions, sometimes referred to as a share handle in some places in the documentation. This init call MUST have a corresponding call to \fIcurl_share_cleanup(3)\fP when all operations using the share are complete. This \fIshare handle\fP is what you pass to curl using the \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, to make that specific curl handle use the data in this share. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE If this function returns NULL, something went wrong (out of memory, etc.) and therefore the share object was not created. .SH SEE ALSO .BR curl_share_cleanup (3), .BR curl_share_setopt (3)	1.24 KB	2025-07-08 09:41
📄 curl_share_setopt.3 .\" generated by cd2nroff 0.1 from curl_share_setopt.md .TH curl_share_setopt 3 "2025-06-27" libcurl .SH NAME curl_share_setopt \- set options for a shared object .SH SYNOPSIS .nf #include <curl/curl.h> CURLSHcode curl_share_setopt(CURLSH share, CURLSHoption option, parameter); .fi .SH DESCRIPTION Set the \fIoption\fP to \fIparameter\fP for the given \fIshare\fP. .SH OPTIONS .IP CURLSHOPT_LOCKFUNC See \fICURLSHOPT_LOCKFUNC(3)\fP. .IP CURLSHOPT_UNLOCKFUNC See \fICURLSHOPT_UNLOCKFUNC(3)\fP. .IP CURLSHOPT_SHARE See \fICURLSHOPT_SHARE(3)\fP. .IP CURLSHOPT_UNSHARE See \fICURLSHOPT_UNSHARE(3)\fP. .IP CURLSHOPT_USERDATA See \fICURLSHOPT_USERDATA(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE CURLSHE_OK (zero) means that the option was set properly, non\-zero means an error occurred as \fI<curl/curl.h>\fP defines. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. .SH SEE ALSO .BR curl_share_cleanup (3), .BR curl_share_init (3)	1.24 KB	2025-07-08 09:41
📄 curl_share_strerror.3 .\" generated by cd2nroff 0.1 from curl_share_strerror.md .TH curl_share_strerror 3 "2025-06-27" libcurl .SH NAME curl_share_strerror \- return string describing error code .SH SYNOPSIS .nf #include <curl/curl.h> const char curl_share_strerror(CURLSHcode errornum); .fi .SH DESCRIPTION The \fIcurl_share_strerror(3)\fP function returns a string describing the \fICURLSHcode\fP error code passed in the argument \fIerrornum\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLSHcode sh; CURLSH share = curl_share_init(); sh = curl_share_setopt(share, CURLSHOPT_SHARE, CURL_LOCK_DATA_CONNECT); if(sh) printf("Error: %s\\n", curl_share_strerror(sh)); } .fi .SH AVAILABILITY Added in curl 7.12.0 .SH RETURN VALUE A pointer to a null\-terminated string. .SH SEE ALSO .BR curl_easy_strerror (3), .BR curl_multi_strerror (3), .BR curl_url_strerror (3), .BR libcurl-errors (3)	938 B	2025-07-08 09:41
📄 curl_slist_append.3 .\" generated by cd2nroff 0.1 from curl_slist_append.md .TH curl_slist_append 3 "2025-06-27" libcurl .SH NAME curl_slist_append \- add a string to an slist .SH SYNOPSIS .nf #include <curl/curl.h> struct curl_slist curl_slist_append(struct curl_slist list, const char string); .fi .SH DESCRIPTION \fIcurl_slist_append(3)\fP appends a string to a linked list of strings. The existing \fBlist\fP should be passed as the first argument and the new list is returned from this function. Pass in NULL in the \fBlist\fP argument to create a new list. The specified \fBstring\fP has been appended when this function returns. \fIcurl_slist_append(3)\fP copies the string. The list should be freed again (after usage) with \fIcurl_slist_free_all(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL handle = curl_easy_init(); struct curl_slist slist = NULL; struct curl_slist temp = NULL; slist = curl_slist_append(slist, "pragma:"); if(!slist) return -1; temp = curl_slist_append(slist, "Accept:"); if(!temp) { curl_slist_free_all(slist); return -1; } slist = temp; curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); curl_easy_perform(handle); curl_slist_free_all(slist); /* free the list again */ } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE A null pointer is returned if anything went wrong, otherwise the new list pointer is returned. To avoid overwriting an existing non\-empty list on failure, the new list should be returned to a temporary variable which can be tested for NULL before updating the original list pointer. .SH SEE ALSO .BR curl_slist_free_all (3)	1.68 KB	2025-07-08 09:41
📄 curl_slist_free_all.3 .\" generated by cd2nroff 0.1 from curl_slist_free_all.md .TH curl_slist_free_all 3 "2025-06-27" libcurl .SH NAME curl_slist_free_all \- free an entire curl_slist list .SH SYNOPSIS .nf #include <curl/curl.h> void curl_slist_free_all(struct curl_slist list); .fi .SH DESCRIPTION curl_slist_free_all() removes all traces of a previously built curl_slist linked list. Passing in a NULL pointer in \fIlist\fP makes this function return immediately with no action. Any use of the \fBlist\fP after this function has been called and have returned, is illegal. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL handle = curl_easy_init(); struct curl_slist slist = NULL; slist = curl_slist_append(slist, "X-libcurl: coolness"); if(!slist) return -1; curl_easy_setopt(handle, CURLOPT_HTTPHEADER, slist); curl_easy_perform(handle); curl_slist_free_all(slist); / free the list again */ } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE Nothing. .SH SEE ALSO .BR curl_slist_append (3)	1.04 KB	2025-07-08 09:41
📄 curl_strequal.3 .\" generated by cd2nroff 0.1 from curl_strequal.md .TH curl_strequal 3 "2025-06-27" libcurl .SH NAME curl_strequal \- compare two strings ignoring case .SH SYNOPSIS .nf #include <curl/curl.h> int curl_strequal(const char str1, const char str2); .fi .SH DESCRIPTION The \fIcurl_strequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case of the characters. It returns a non\-zero (TRUE) integer if the strings are identical. This function uses plain ASCII based comparisons completely disregarding the locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive string comparisons usually work. This function is provided by libcurl to enable applications to compare strings in a truly portable manner. There are no standard portable case insensitive string comparison functions. This function works on all platforms. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(int argc, char *argv) { const char name = "compare"; if(curl_strequal(name, argv[1])) printf("Name and input matches\\n"); } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE Non\-zero if the strings are identical. Zero if they are not. .SH SEE ALSO .BR curl_strnequal (3), .BR strcasecmp (3), .BR strcmp (3)	1.26 KB	2025-07-08 09:41
📄 curl_strnequal.3 .\" generated by cd2nroff 0.1 from curl_strnequal.md .TH curl_strnequal 3 "2025-06-27" libcurl .SH NAME curl_strnequal \- compare two strings ignoring case .SH SYNOPSIS .nf #include <curl/curl.h> int curl_strnequal(const char str1, const char str2, size_t length); .fi .SH DESCRIPTION The \fIcurl_strnequal(3)\fP function compares the two strings \fIstr1\fP and \fIstr2\fP, ignoring the case of the characters. It returns a non\-zero (TRUE) integer if the strings are identical. This function compares no more than the first \fIlength\fP bytes of \fIstr1\fP and \fIstr2\fP. This function uses plain ASCII based comparisons completely disregarding the locale \- contrary to how \fBstrcasecmp\fP and other system case insensitive string comparisons usually work. This function is provided by libcurl to enable applications to compare strings in a truly portable manner. There are no standard portable case insensitive string comparison functions. This function works on all platforms. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(int argc, char *argv) { const char name = "compare"; if(curl_strnequal(name, argv[1], 5)) printf("Name and input matches in the 5 first bytes\\n"); } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE Non\-zero if the strings are identical. Zero if they are not. .SH SEE ALSO .BR curl_strequal (3), .BR strcasecmp (3), .BR strcmp (3)	1.39 KB	2025-07-08 09:41
📄 curl_unescape.3 .\" generated by cd2nroff 0.1 from curl_unescape.md .TH curl_unescape 3 "2025-06-27" libcurl .SH NAME curl_unescape \- URL decode a string .SH SYNOPSIS .nf #include <curl/curl.h> char curl_unescape(const char input, int length); .fi .SH DESCRIPTION Deprecated. Use \fIcurl_easy_unescape(3)\fP instead. This function converts the URL encoded string \fBinput\fP to a "plain string" and return that as a new allocated string. All input characters that are URL encoded (%XX where XX is a two\-digit hexadecimal number) are converted to their plain text versions. If the \fBlength\fP argument is set to 0, \fIcurl_unescape(3)\fP calls strlen() on \fBinput\fP to find out the size. You must \fIcurl_free(3)\fP the returned string when you are done with it. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURL curl = curl_easy_init(); if(curl) { char decoded = curl_unescape("%63%75%72%6c", 12); if(decoded) { /* do not assume printf() works on the decoded data / printf("Decoded: "); / ... */ curl_free(decoded); } } } .fi .SH DEPRECATED Since 7.15.4, \fIcurl_easy_unescape(3)\fP should be used. This function might be removed in a future release. .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE A pointer to a null\-terminated string or NULL if it failed. .SH SEE ALSO .BR RFC 2396, .BR curl_easy_escape (3), .BR curl_easy_unescape (3), .BR curl_free (3)	1.42 KB	2025-07-08 09:41
📄 curl_url.3 .\" generated by cd2nroff 0.1 from curl_url.md .TH curl_url 3 "2025-06-27" libcurl .SH NAME curl_url \- create a URL handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLU curl_url(); .fi .SH DESCRIPTION This function allocates a URL object and returns a \fICURLU\fP handle for it, to be used as input to all other URL API functions. This is a handle to a URL object that holds or can hold URL components for a single URL. When the object is first created, there is of course no components stored. They are then set in the object with the \fIcurl_url_set(3)\fP function. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLUcode rc; CURLU url = curl_url(); rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); if(!rc) { char scheme; rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); if(!rc) { printf("the scheme is %s\\n", scheme); curl_free(scheme); } curl_url_cleanup(url); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE Returns a \fBCURLU \fP if successful, or NULL if out of memory. .SH SEE ALSO .BR CURLOPT_CURLU (3), .BR curl_url_cleanup (3), .BR curl_url_dup (3), .BR curl_url_get (3), .BR curl_url_set (3), .BR curl_url_strerror (3)	1.24 KB	2025-07-08 09:41
📄 curl_url_cleanup.3 .\" generated by cd2nroff 0.1 from curl_url_cleanup.md .TH curl_url_cleanup 3 "2025-06-27" libcurl .SH NAME curl_url_cleanup \- free the URL handle .SH SYNOPSIS .nf #include <curl/curl.h> void curl_url_cleanup(CURLU handle); .fi .SH DESCRIPTION Frees all the resources associated with the given \fICURLU\fP handle. Passing in a NULL pointer in \fIhandle\fP makes this function return immediately with no action. Any use of the \fBhandle\fP after this function has been called and have returned, is illegal. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLU url = curl_url(); curl_url_set(url, CURLUPART_URL, "https://example.com", 0); curl_url_cleanup(url); } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE none .SH SEE ALSO .BR CURLOPT_CURLU (3), .BR curl_url (3), .BR curl_url_dup (3), .BR curl_url_get (3), .BR curl_url_set (3)	908 B	2025-07-08 09:41
📄 curl_url_dup.3 .\" generated by cd2nroff 0.1 from curl_url_dup.md .TH curl_url_dup 3 "2025-06-27" libcurl .SH NAME curl_url_dup \- duplicate a URL handle .SH SYNOPSIS .nf #include <curl/curl.h> CURLU curl_url_dup(const CURLU inhandle); .fi .SH DESCRIPTION Duplicates the URL object the input \fICURLU\fP \fIinhandle\fP identifies and returns a pointer to the copy as a new \fICURLU\fP handle. The new handle also needs to be freed with \fIcurl_url_cleanup(3)\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLUcode rc; CURLU url = curl_url(); CURLU url2; rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); if(!rc) { url2 = curl_url_dup(url); /* clone it */ curl_url_cleanup(url2); } curl_url_cleanup(url); } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE Returns a pointer to a new \fICURLU\fP handle or NULL if out of memory. .SH SEE ALSO .BR CURLOPT_CURLU (3), .BR curl_url (3), .BR curl_url_cleanup (3), .BR curl_url_get (3), .BR curl_url_set (3)	1.02 KB	2025-07-08 09:41
📄 curl_url_get.3 .\" generated by cd2nroff 0.1 from curl_url_get.md .TH curl_url_get 3 "2025-06-27" libcurl .SH NAME curl_url_get \- extract a part from a URL .SH SYNOPSIS .nf #include <curl/curl.h> CURLUcode curl_url_get(const CURLU url, CURLUPart part, char content, unsigned int flags); .fi .SH DESCRIPTION Given a \fIurl\fP handle of a URL object, this function extracts an individual piece or the full URL from it. The \fIpart\fP argument specifies which part to extract (see list below) and \fIcontent\fP points to a \(aqchar \(aq to get updated to point to a newly allocated string with the contents. The \fIflags\fP argument is a bitmask with individual features. The returned content pointer must be freed with \fIcurl_free(3)\fP after use. .SH FLAGS The flags argument is zero, one or more bits set in a bitmask. .IP CURLU_DEFAULT_PORT If the handle has no port stored, this option makes \fIcurl_url_get(3)\fP return the default port for the used scheme. .IP CURLU_DEFAULT_SCHEME If the handle has no scheme stored, this option makes \fIcurl_url_get(3)\fP return the default scheme instead of error. .IP CURLU_NO_DEFAULT_PORT Instructs \fIcurl_url_get(3)\fP to not return a port number if it matches the default port for the scheme. .IP CURLU_URLDECODE Asks \fIcurl_url_get(3)\fP to URL decode the contents before returning it. It does not decode the scheme, the port number or the full URL. The query component also gets plus\-to\-space conversion as a bonus when this bit is set. Note that this URL decoding is charset unaware and you get a null\-terminated string back with data that could be intended for a particular encoding. If there are byte values lower than 32 in the decoded string, the get operation returns an error instead. .IP CURLU_URLENCODE If set, \fIcurl_url_get(3)\fP URL encodes the hostname part when a full URL is retrieved. If not set (default), libcurl returns the URL with the hostname raw to support IDN names to appear as\-is. IDN hostnames are typically using non\-ASCII bytes that otherwise gets percent\-encoded. Note that even when not asking for URL encoding, the \(aq%\(aq (byte 37) is URL encoded to make sure the hostname remains valid. .IP CURLU_PUNYCODE If set and \fICURLU_URLENCODE\fP is not set, and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP parts, libcurl returns the host name in its punycode version if it contains any non\-ASCII octets (and is an IDN name). If libcurl is built without IDN capabilities, using this bit makes \fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname contains anything outside the ASCII range. (Added in curl 7.88.0) .IP CURLU_PUNY2IDN If set and asked to retrieve the \fBCURLUPART_HOST\fP or \fBCURLUPART_URL\fP parts, libcurl returns the hostname in its IDN (International Domain Name) UTF\-8 version if it otherwise is a punycode version. If the punycode name cannot be converted to IDN correctly, libcurl returns \fICURLUE_BAD_HOSTNAME\fP. If libcurl is built without IDN capabilities, using this bit makes \fIcurl_url_get(3)\fP return \fICURLUE_LACKS_IDN\fP if the hostname is using punycode. (Added in curl 8.3.0) .IP CURLU_GET_EMPTY When this flag is used in curl_url_get(), it makes the function return empty query and fragments parts or when used in the full URL. By default, libcurl otherwise considers empty parts non\-existing. An empty query part is one where this is nothing following the question mark (before the possible fragment). An empty fragments part is one where there is nothing following the hash sign. (Added in curl 8.8.0) .IP CURLU_NO_GUESS_SCHEME When this flag is used in curl_url_get(), it treats the scheme as non\-existing if it was set as a result of a previous guess; when CURLU_GUESS_SCHEME was used parsing a URL. Using this flag when getting CURLUPART_SCHEME if the scheme was set as the result of a guess makes curl_url_get() return CURLUE_NO_SCHEME. Using this flag when getting CURLUPART_URL if the scheme was set as the result of a guess makes curl_url_get() return the full URL without the scheme component. Such a URL can then only be parsed with curl_url_set() if CURLU_GUESS_SCHEME is used. (Added in curl 8.9.0) .SH PARTS .IP CURLUPART_URL When asked to return the full URL, \fIcurl_url_get(3)\fP returns a slightly cleaned up version of the complete URL using all available parts. We advise using the \fICURLU_PUNYCODE\fP option to get the URL as "normalized" as possible since IDN allows hostnames to be written in many different ways that still end up the same punycode version. Zero\-length queries and fragments are excluded from the URL unless CURLU_GET_EMPTY is set. .IP CURLUPART_SCHEME Scheme cannot be URL decoded on get. .IP CURLUPART_USER .IP CURLUPART_PASSWORD .IP CURLUPART_OPTIONS The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. The URL API still allows users to set and get this field independently of scheme when not parsing full URLs. .IP CURLUPART_HOST The hostname. If it is an IPv6 numeric address, the zone id is not part of it but is provided separately in \fICURLUPART_ZONEID\fP. IPv6 numerical addresses are returned within brackets ([]). IPv6 names are normalized when set, which should make them as short as possible while maintaining correct syntax. .IP CURLUPART_ZONEID If the hostname is a numeric IPv6 address, this field might also be set. .IP CURLUPART_PORT A port cannot be URL decoded on get. This number is returned in a string just like all other parts. That string is guaranteed to hold a valid port number in ASCII using base 10. .IP CURLUPART_PATH The \fIpart\fP is always at least a slash (\(aq/\(aq) even if no path was supplied in the URL. A URL path always starts with a slash. .IP CURLUPART_QUERY The initial question mark that denotes the beginning of the query part is a delimiter only. It is not part of the query contents. A not\-present query returns \fIpart\fP set to NULL. A zero\-length query returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set. The query part gets pluses converted to space when asked to URL decode on get with the CURLU_URLDECODE bit. .IP CURLUPART_FRAGMENT The initial hash sign that denotes the beginning of the fragment is a delimiter only. It is not part of the fragment contents. A not\-present fragment returns \fIpart\fP set to NULL. A zero\-length fragment returns \fIpart\fP as NULL unless CURLU_GET_EMPTY is set. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLUcode rc; CURLU url = curl_url(); rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); if(!rc) { char scheme; rc = curl_url_get(url, CURLUPART_SCHEME, &scheme, 0); if(!rc) { printf("the scheme is %s\\n", scheme); curl_free(scheme); } curl_url_cleanup(url); } } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE Returns a CURLUcode error value, which is CURLUE_OK (0) if everything went fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. If this function returns an error, no URL part is returned. .SH SEE ALSO .BR CURLOPT_CURLU (3), .BR curl_url (3), .BR curl_url_cleanup (3), .BR curl_url_dup (3), .BR curl_url_set (3), .BR curl_url_strerror (3)	7.26 KB	2025-07-08 09:41
📄 curl_url_set.3 .\" generated by cd2nroff 0.1 from curl_url_set.md .TH curl_url_set 3 "2025-06-27" libcurl .SH NAME curl_url_set \- set a URL part .SH SYNOPSIS .nf #include <curl/curl.h> CURLUcode curl_url_set(CURLU url, CURLUPart part, const char content, unsigned int flags); .fi .SH DESCRIPTION The \fIurl\fP handle to work on, passed in as the first argument, must be a handle previously created by \fIcurl_url(3)\fP or \fIcurl_url_dup(3)\fP. This function sets or updates individual URL components, or parts, held by the URL object the handle identifies. The \fIpart\fP argument should identify the particular URL part (see list below) to set or change, with \fIcontent\fP pointing to a null\-terminated string with the new contents for that URL part. The contents should be in the form and encoding they would use in a URL: URL encoded. When setting a part in the URL object that was previously already set, it replaces the data that was previously stored for that part with the new \fIcontent\fP. The caller does not have to keep \fIcontent\fP around after a successful call as this function copies the content. Setting a part to a NULL pointer removes that part\(aqs contents from the \fICURLU\fP handle. This function has an 8 MB maximum length limit for all provided input strings. In the real world, excessively long fields in URLs cause problems even if this function accepts them. When setting or updating contents of individual URL parts, \fIcurl_url_set(3)\fP might accept data that would not be otherwise possible to set in the string when it gets populated as a result of a full URL parse. Beware. If done so, extracting a full URL later on from such components might render an invalid URL. The \fIflags\fP argument is a bitmask with independent features. .SH PARTS .IP CURLUPART_URL Allows the full URL of the handle to be replaced. If the handle already is populated with a URL, the new URL can be relative to the previous. When successfully setting a new URL, relative or absolute, the handle contents is replaced with the components of the newly set URL. Pass a pointer to a null\-terminated string to the \fIurl\fP parameter. The string must point to a correctly formatted "RFC 3986+" URL or be a NULL pointer. The URL parser only understands and parses the subset of URLS that are \&"hierarchical" and therefore contain a \fI://\fP separator \- not the ones that are normally specified with only a colon separator. By default this API only parses URLs using schemes for protocols that are supported built\-in. To make libcurl parse URLs generically even for schemes it does not know about, the \fBCURLU_NON_SUPPORT_SCHEME\fP flags bit must be set. Otherwise, this function returns \fICURLUE_UNSUPPORTED_SCHEME\fP for URL schemes it does not recognize. Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed in the URL. When a full URL is set (parsed), the hostname component is stored URL decoded. It is considered fine to set a blank URL ("") as a redirect, but not as a normal URL. Therefore, setting a "" URL works fine if the handle already holds a URL, otherwise it triggers an error. .IP CURLUPART_SCHEME Scheme cannot be URL decoded on set. libcurl only accepts setting schemes up to 40 bytes long. .IP CURLUPART_USER If only the user part is set and not the password, the URL is represented with a blank password. .IP CURLUPART_PASSWORD If only the password part is set and not the user, the URL is represented with a blank user. .IP CURLUPART_OPTIONS The options field is an optional field that might follow the password in the userinfo part. It is only recognized/used when parsing URLs for the following schemes: pop3, smtp and imap. This function however allows users to independently set this field. .IP CURLUPART_HOST The hostname. If it is International Domain Name (IDN) the string must then be encoded as your locale says or UTF\-8 (when WinIDN is used). If it is a bracketed IPv6 numeric address it may contain a zone id (or you can use \fICURLUPART_ZONEID\fP). Note that if you set an IPv6 address, it gets ruined and causes an error if you also set the CURLU_URLENCODE flag. Unless \fICURLU_NO_AUTHORITY\fP is set, a blank hostname is not allowed to set. .IP CURLUPART_ZONEID If the hostname is a numeric IPv6 address, this field can also be set. .IP CURLUPART_PORT The port number cannot be URL encoded on set. The given port number is provided as a string and the decimal number in it must be between 0 and 65535. Anything else returns an error. .IP CURLUPART_PATH If a path is set in the URL without a leading slash, a slash is prepended automatically. .IP CURLUPART_QUERY The query part gets spaces converted to pluses when asked to URL encode on set with the \fICURLU_URLENCODE\fP bit. If used together with the \fICURLU_APPENDQUERY\fP bit, the provided part is appended on the end of the existing query. The question mark in the URL is not part of the actual query contents. .IP CURLUPART_FRAGMENT The hash sign in the URL is not part of the actual fragment contents. .SH FLAGS The flags argument is zero, one or more bits set in a bitmask. .IP CURLU_APPENDQUERY Can be used when setting the \fICURLUPART_QUERY\fP component. The provided new part is then appended at the end of the existing query \- and if the previous part did not end with an ampersand (&), an ampersand gets inserted before the new appended part. When \fICURLU_APPENDQUERY\fP is used together with \fICURLU_URLENCODE\fP, the first \(aq=\(aq symbol is not URL encoded. .IP CURLU_NON_SUPPORT_SCHEME If set, allows \fIcurl_url_set(3)\fP to set a non\-supported scheme. It then of course cannot know if the provided scheme is a valid one or not. .IP CURLU_URLENCODE When set, \fIcurl_url_set(3)\fP URL encodes the part on entry, except for \fBscheme\fP, \fBport\fP and \fBURL\fP. When setting the path component with URL encoding enabled, the slash character is skipped. The query part gets space\-to\-plus converted before the URL conversion is applied. This URL encoding is charset unaware and converts the input in a byte\-by\-byte manner. .IP CURLU_DEFAULT_SCHEME If set, allows the URL to be set without a scheme and then sets that to the default scheme: HTTPS. Overrides the \fICURLU_GUESS_SCHEME\fP option if both are set. .IP CURLU_GUESS_SCHEME If set, allows the URL to be set without a scheme and it instead "guesses" which scheme that was intended based on the hostname. If the outermost subdomain name matches DICT, FTP, IMAP, LDAP, POP3 or SMTP then that scheme is used, otherwise it picks HTTP. Conflicts with the \fICURLU_DEFAULT_SCHEME\fP option which takes precedence if both are set. If guessing is not allowed and there is no default scheme set, trying to parse a URL without a scheme returns error. If the scheme ends up set as a result of guessing, i.e. it is not actually present in the parsed URL, it can later be figured out by using the \fBCURLU_NO_GUESS_SCHEME\fP flag when subsequently getting the URL or the scheme with \fIcurl_url_get(3)\fP. .IP CURLU_NO_AUTHORITY If set, skips authority checks. The RFC allows individual schemes to omit the host part (normally the only mandatory part of the authority), but libcurl cannot know whether this is permitted for custom schemes. Specifying the flag permits empty authority sections, similar to how file scheme is handled. .IP CURLU_PATH_AS_IS When set for \fBCURLUPART_URL\fP, this skips the normalization of the path. That is the procedure where libcurl otherwise removes sequences of dot\-slash and dot\-dot etc. The same option used for transfers is called \fICURLOPT_PATH_AS_IS(3)\fP. .IP CURLU_ALLOW_SPACE If set, the URL parser allows space (ASCII 32) where possible. The URL syntax does normally not allow spaces anywhere, but they should be encoded as %20 or \(aq+\(aq. When spaces are allowed, they are still not allowed in the scheme. When space is used and allowed in a URL, it is stored as\-is unless \fICURLU_URLENCODE\fP is also set, which then makes libcurl URL encode the space before stored. This affects how the URL is constructed when \fIcurl_url_get(3)\fP is subsequently used to extract the full URL or individual parts. (Added in 7.78.0) .IP CURLU_DISALLOW_USER If set, the URL parser does not accept embedded credentials for the \fBCURLUPART_URL\fP, and instead returns \fBCURLUE_USER_NOT_ALLOWED\fP for such URLs. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLUcode rc; CURLU url = curl_url(); rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); if(!rc) { / change it to an FTP URL */ rc = curl_url_set(url, CURLUPART_SCHEME, "ftp", 0); } curl_url_cleanup(url); } .fi .SH AVAILABILITY Added in curl 7.62.0 .SH RETURN VALUE Returns a \fICURLUcode\fP error value, which is CURLUE_OK (0) if everything went fine. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. The input string passed to \fIcurl_url_set(3)\fP must be shorter than eight million bytes. Otherwise this function returns \fBCURLUE_MALFORMED_INPUT\fP. If this function returns an error, no URL part is set. .SH SEE ALSO .BR CURLOPT_CURLU (3), .BR curl_url (3), .BR curl_url_cleanup (3), .BR curl_url_dup (3), .BR curl_url_get (3), .BR curl_url_strerror (3)	9.13 KB	2025-07-08 09:41
📄 curl_url_strerror.3 .\" generated by cd2nroff 0.1 from curl_url_strerror.md .TH curl_url_strerror 3 "2025-06-27" libcurl .SH NAME curl_url_strerror \- return string describing error code .SH SYNOPSIS .nf #include <curl/curl.h> const char curl_url_strerror(CURLUcode errornum); .fi .SH DESCRIPTION This function returns a string describing the CURLUcode error code passed in the argument \fIerrornum\fP. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { CURLUcode rc; CURLU url = curl_url(); rc = curl_url_set(url, CURLUPART_URL, "https://example.com", 0); if(rc) printf("URL error: %s\\n", curl_url_strerror(rc)); curl_url_cleanup(url); } .fi .SH AVAILABILITY Added in curl 7.80.0 .SH RETURN VALUE A pointer to a null\-terminated string. .SH SEE ALSO .BR curl_easy_strerror (3), .BR curl_multi_strerror (3), .BR curl_share_strerror (3), .BR curl_url_get (3), .BR curl_url_set (3), .BR libcurl-errors (3)	949 B	2025-07-08 09:41
📄 curl_version.3 .\" generated by cd2nroff 0.1 from curl_version.md .TH curl_version 3 "2025-06-27" libcurl .SH NAME curl_version \- returns the libcurl version string .SH SYNOPSIS .nf #include <curl/curl.h> char *curl_version(); .fi .SH DESCRIPTION Returns a human readable string with the version number of libcurl and some of its important components (like OpenSSL version). For MultiSSL builds the string contains all SSL backend names and the inactive backend names are in parentheses. For example "(OpenSSL/3.0.8) Schannel" or \&"OpenSSL/3.0.8 (Schannel)". We recommend using \fIcurl_version_info(3)\fP instead. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { printf("libcurl version %s\\n", curl_version()); } .fi .SH AVAILABILITY Added in curl 7.1 .SH RETURN VALUE A pointer to a null\-terminated string. The string resides in a statically allocated buffer and must not be freed by the caller. .SH SEE ALSO .BR curl_version_info (3)	979 B	2025-07-08 09:41
📄 curl_version_info.3 .\" generated by cd2nroff 0.1 from curl_version_info.md .TH curl_version_info 3 "2025-06-27" libcurl .SH NAME curl_version_info \- returns runtime libcurl version info .SH SYNOPSIS .nf #include <curl/curl.h> curl_version_info_data curl_version_info(CURLversion age); .fi .SH DESCRIPTION Returns a pointer to a filled in static struct with information about various features in the running version of libcurl. \fIage\fP should be set to the version of this functionality by the time you write your program. This way, libcurl always returns a proper struct that your program understands, while programs in the future might get a different struct. \fBCURLVERSION_NOW\fP is the most recent one for the library you have installed: .nf data = curl_version_info(CURLVERSION_NOW); .fi Applications should use this information to judge if things are possible to do or not, instead of using compile\-time checks, as dynamic/DLL libraries can be changed independent of applications. This function can alter the returned static data as long as \fIcurl_global_init(3)\fP has not been called. It is therefore not thread\-safe before libcurl initialization occurs. The curl_version_info_data struct looks like this .nf typedef struct { CURLversion age; / see description below / const char version; /* human readable string / unsigned int version_num; / numeric representation / const char host; /* human readable string / int features; / bitmask, see below / char ssl_version; /* human readable string / long ssl_version_num; / not used, always zero / const char libz_version; /* human readable string / const char const protocols; / protocols / / when 'age' is CURLVERSION_SECOND or higher, the members below exist / const char ares; /* human readable string / int ares_num; / number / / when 'age' is CURLVERSION_THIRD or higher, the members below exist / const char libidn; /* human readable string / / when 'age' is CURLVERSION_FOURTH or higher (>= 7.16.1), the members below exist / int iconv_ver_num; / '_libiconv_version' if iconv support enabled / const char libssh_version; /* human readable string / / when 'age' is CURLVERSION_FIFTH or higher (>= 7.57.0), the members below exist / unsigned int brotli_ver_num; / Numeric Brotli version (MAJOR << 24) \| (MINOR << 12) \| PATCH / const char brotli_version; /* human readable string. / / when 'age' is CURLVERSION_SIXTH or higher (>= 7.66.0), the members below exist / unsigned int nghttp2_ver_num; / Numeric nghttp2 version (MAJOR << 16) \| (MINOR << 8) \| PATCH / const char nghttp2_version; /* human readable string. / const char quic_version; /* human readable quic (+ HTTP/3) library + version or NULL / / when 'age' is CURLVERSION_SEVENTH or higher (>= 7.70.0), the members below exist / const char cainfo; /* the built-in default CURLOPT_CAINFO, might be NULL / const char capath; /* the built-in default CURLOPT_CAPATH, might be NULL / / when 'age' is CURLVERSION_EIGHTH or higher (>= 7.71.0), the members below exist / unsigned int zstd_ver_num; / Numeric Zstd version (MAJOR << 24) \| (MINOR << 12) \| PATCH / const char zstd_version; /* human readable string. / / when 'age' is CURLVERSION_NINTH or higher (>= 7.75.0), the members below exist / const char hyper_version; /* human readable string. / / when 'age' is CURLVERSION_TENTH or higher (>= 7.77.0), the members below exist / const char gsasl_version; /* human readable string. / / when 'age' is CURLVERSION_ELEVENTH or higher (>= 7.87.0), the members below exist / const char const feature_names; / Feature names. / / when 'age' is CURLVERSION_TWELFTH or higher (>= 8.8.0), the members below exist / const char const rtmp_version; / human readable string / } curl_version_info_data; .fi \fIage\fP describes what the age of this struct is. The number depends on how new the libcurl you are using is. You are however guaranteed to get a struct that you have a matching struct for in the header, as you tell libcurl your \&"age" with the input argument. \fIversion\fP is just an ASCII string for the libcurl version. \fIversion_num\fP is a 24 bit number created like this: <8 bits major number> \| <8 bits minor number> \| <8 bits patch number>. Version 7.9.8 is therefore returned as 0x070908. \fIhost\fP is an ASCII string showing what host information that this libcurl was built for. As discovered by a configure script or set by the build environment. \fIfeatures\fP is a bit mask representing available features. It can have none, one or more bits set. The use of this field is deprecated: use \fIfeature_names\fP instead. The feature names description below lists the associated bits. \fIfeature_names\fP is a pointer to an array of string pointers, containing the names of the features that libcurl supports. The array is terminated by a NULL entry. See the list of features names below. \fIssl_version\fP is an ASCII string for the TLS library name + version used. If libcurl has no SSL support, this is NULL. For example "Schannel", "Secure Transport" or "OpenSSL/1.1.0g". For MultiSSL builds the string contains all SSL backend names and the inactive backend names are in parentheses. For example "(OpenSSL/3.0.8) Schannel" or "OpenSSL/3.0.8 (Schannel)". \fIssl_version_num\fP is always 0. \fIlibz_version\fP is an ASCII string (there is no numerical version). If libcurl has no libz support, this is NULL. \fIprotocols\fP is a pointer to an array of char pointers, containing the names protocols that libcurl supports (using lowercase letters). The protocol names are the same as would be used in URLs. The array is terminated by a NULL entry. .SH FEATURES .IP alt-svc \fIfeatures\fP mask bit: CURL_VERSION_ALTSVC HTTP Alt\-Svc parsing and the associated options (Added in 7.64.1) .IP AsynchDNS \fIfeatures\fP mask bit: CURL_VERSION_ASYNCHDNS libcurl was built with support for asynchronous name lookups, which allows more exact timeouts (even on Windows) and less blocking when using the multi interface. (added in 7.10.7) .IP brotli \fIfeatures\fP mask bit: CURL_VERSION_BROTLI supports HTTP Brotli content encoding using libbrotlidec (Added in 7.57.0) .IP asyn-rr \fIfeatures\fP mask bit: non\-existent libcurl was built to use c\-ares for EXPERIMENTAL HTTPS resource record resolves, but uses the threaded resolver for "normal" resolves (Added in 8.12.0) .IP Debug \fIfeatures\fP mask bit: CURL_VERSION_DEBUG libcurl was built with debug capabilities (added in 7.10.6) .IP ECH \fIfeatures\fP mask bit: non\-existent libcurl was built with ECH support (experimental, added in 8.8.0) .IP gsasl \fIfeatures\fP mask bit: CURL_VERSION_GSASL libcurl was built with libgsasl and thus with some extra SCRAM\-SHA authentication methods. (added in 7.76.0) .IP GSS-API \fIfeatures\fP mask bit: CURL_VERSION_GSSAPI libcurl was built with support for GSS\-API. This makes libcurl use provided functions for Kerberos and SPNEGO authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.38.0) .IP HSTS \fIfeatures\fP mask bit: CURL_VERSION_HSTS libcurl was built with support for HSTS (HTTP Strict Transport Security) (Added in 7.74.0) .IP HTTP2 \fIfeatures\fP mask bit: CURL_VERSION_HTTP2 libcurl was built with support for HTTP2. (Added in 7.33.0) .IP HTTP3 \fIfeatures\fP mask bit: CURL_VERSION_HTTP3 HTTP/3 and QUIC support are built\-in (Added in 7.66.0) .IP HTTPS-proxy \fIfeatures\fP mask bit: CURL_VERSION_HTTPS_PROXY libcurl was built with support for HTTPS\-proxy. (Added in 7.52.0) .IP HTTPSRR \fIfeatures\fP mask bit: non\-existent libcurl was built with EXPERIMENTAL support for HTTPS resource records (Added in 8.12.0) .IP IDN \fIfeatures\fP mask bit: CURL_VERSION_IDN libcurl was built with support for IDNA, domain names with international letters. (Added in 7.12.0) .IP IPv6 \fIfeatures\fP mask bit: CURL_VERSION_IPV6 supports IPv6 .IP Kerberos \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS5 supports Kerberos V5 authentication for FTP, IMAP, LDAP, POP3, SMTP and SOCKSv5 proxy. (Added in 7.40.0) .IP Largefile \fIfeatures\fP mask bit: CURL_VERSION_LARGEFILE libcurl was built with support for large files. (Added in 7.11.1) .IP libz \fIfeatures\fP mask bit: CURL_VERSION_LIBZ supports HTTP deflate using libz (Added in 7.10) .IP MultiSSL \fIfeatures\fP mask bit: CURL_VERSION_MULTI_SSL libcurl was built with multiple SSL backends. For details, see \fIcurl_global_sslset(3)\fP. (Added in 7.56.0) .IP NTLM \fIfeatures\fP mask bit: CURL_VERSION_NTLM supports HTTP NTLM (added in 7.10.6) .IP NTLM_WB \fIfeatures\fP mask bit: CURL_VERSION_NTLM_WB libcurl was built with support for NTLM delegation to a winbind helper. (Added in 7.22.0) This feature was removed from curl in 8.8.0. .IP PSL \fIfeatures\fP mask bit: CURL_VERSION_PSL libcurl was built with support for Mozilla\(aqs Public Suffix List. This makes libcurl ignore cookies with a domain that is on the list. (Added in 7.47.0) .IP SPNEGO \fIfeatures\fP mask bit: CURL_VERSION_SPNEGO libcurl was built with support for SPNEGO authentication (Simple and Protected GSS\-API Negotiation Mechanism, defined in RFC 2478.) (added in 7.10.8) .IP SSL \fIfeatures\fP mask bit: CURL_VERSION_SSL supports SSL (HTTPS/FTPS) (Added in 7.10) .IP SSLS-EXPORT \fIfeatures\fP mask bit: non\-existent libcurl was built with SSL session import/export support (experimental, added in 8.12.0) .IP SSPI \fIfeatures\fP mask bit: CURL_VERSION_SSPI libcurl was built with support for SSPI. This is only available on Windows and makes libcurl use Windows\-provided functions for Kerberos, NTLM, SPNEGO and Digest authentication. It also allows libcurl to use the current user credentials without the app having to pass them on. (Added in 7.13.2) .IP threadsafe \fIfeatures\fP mask bit: CURL_VERSION_THREADSAFE libcurl was built with thread\-safety support (Atomic or SRWLOCK) to protect curl initialization. (Added in 7.84.0) See \fIlibcurl\-thread(3)\fP .IP TLS-SRP \fIfeatures\fP mask bit: CURL_VERSION_TLSAUTH_SRP libcurl was built with support for TLS\-SRP (in one or more of the built\-in TLS backends). (Added in 7.21.4) .IP TrackMemory \fIfeatures\fP mask bit: CURL_VERSION_CURLDEBUG libcurl was built with memory tracking debug capabilities. This is mainly of interest for libcurl hackers. (added in 7.19.6) .IP Unicode \fIfeatures\fP mask bit: CURL_VERSION_UNICODE libcurl was built with Unicode support on Windows. This makes non\-ASCII characters work in filenames and options passed to libcurl. (Added in 7.72.0) .IP UnixSockets \fIfeatures\fP mask bit: CURL_VERSION_UNIX_SOCKETS libcurl was built with support for Unix domain sockets. (Added in 7.40.0) .IP zstd \fIfeatures\fP mask bit: CURL_VERSION_ZSTD supports HTTP zstd content encoding using zstd library (Added in 7.72.0) .IP "no name" \fIfeatures\fP mask bit: CURL_VERSION_CONV libcurl was built with support for character conversions provided by callbacks. Always 0 since 7.82.0. (Added in 7.15.4, deprecated.) .IP "no name" \fIfeatures\fP mask bit: CURL_VERSION_GSSNEGOTIATE supports HTTP GSS\-Negotiate (added in 7.10.6, deprecated in 7.38.0) .IP "no name" \fIfeatures\fP mask bit: CURL_VERSION_KERBEROS4 supports Kerberos V4 (when using FTP). Legacy bit. Deprecated since 7.33.0. .SH PROTOCOLS This functionality affects all supported protocols .SH EXAMPLE .nf int main(void) { curl_version_info_data *ver = curl_version_info(CURLVERSION_NOW); printf("libcurl version %u.%u.%u\\n", (ver->version_num >> 16) & 0xff, (ver->version_num >> 8) & 0xff, ver->version_num & 0xff); } .fi .SH AVAILABILITY Added in curl 7.10 .SH RETURN VALUE A pointer to a curl_version_info_data struct. .SH SEE ALSO .BR curl_version (3)	11.92 KB	2025-07-08 09:41
📄 curl_ws_meta.3 .\" generated by cd2nroff 0.1 from curl_ws_meta.md .TH curl_ws_meta 3 "2025-06-27" libcurl .SH NAME curl_ws_meta \- meta data WebSocket information .SH SYNOPSIS .nf #include <curl/curl.h> const struct curl_ws_frame curl_ws_meta(CURL curl); .fi .SH DESCRIPTION When the write callback (\fICURLOPT_WRITEFUNCTION(3)\fP) is invoked on received WebSocket traffic, \fIcurl_ws_meta(3)\fP can be called from within the callback to provide additional information about the current frame. This function only works from within the callback, and only when receiving WebSocket data. This function requires an easy handle as input argument for libcurl to know what transfer the question is about, but as there is no such pointer provided to the callback by libcurl itself, applications that want to use \fIcurl_ws_meta(3)\fP need to pass it on to the callback on its own. .SH struct curl_ws_frame .nf struct curl_ws_frame { int age; int flags; curl_off_t offset; curl_off_t bytesleft; size_t len; }; .fi .IP age This field specify the age of this struct. It is always zero for now. .IP flags This is a bitmask with individual bits set that describes the WebSocket data. See the list below. .IP offset When this chunk is a continuation of frame data already delivered, this is the offset into the final frame data where this piece belongs to. .IP bytesleft If this is not a complete fragment, the \fIbytesleft\fP field informs about how many additional bytes are expected to arrive before this fragment is complete. .IP len The length of the current data chunk. .SH FLAGS The \fImessage type\fP flags (CURLWS_TEXT/BINARY/CLOSE/PING/PONG) are mutually exclusive. .IP CURLWS_TEXT This is a message with text data. Note that this makes a difference to WebSocket but libcurl itself does not make any verification of the content or precautions that you actually receive valid UTF\-8 content. .IP CURLWS_BINARY This is a message with binary data. .IP CURLWS_CLOSE This is a close message. No more data follows. It may contain a 2\-byte unsigned integer in network byte order that indicates the close reason and may additionally contain up to 123 bytes of further textual payload for a total of at most 125 bytes. libcurl does not verify that the textual description is valid UTF\-8. .IP CURLWS_PING This is a ping message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF\-8. Upon receiving a ping message, libcurl automatically responds with a pong message unless the \fBCURLWS_NOAUTOPONG\fP or \fBCURLWS_RAW_MODE\fP bit of \fICURLOPT_WS_OPTIONS(3)\fP is set. .IP CURLWS_PONG This is a pong message. It may contain up to 125 bytes of payload text. libcurl does not verify that the payload is valid UTF\-8. .IP CURLWS_CONT Can only occur in conjunction with CURLWS_TEXT or CURLWS_BINARY. This is not the final fragment of the message, it implies that there is another fragment coming as part of the same message. The application must reassemble the fragments to receive the complete message. Only a single fragmented message can be transmitted at a time, but it may be interrupted by CURLWS_CLOSE, CURLWS_PING or CURLWS_PONG frames. .SH PROTOCOLS This functionality affects ws only .SH EXAMPLE .nf /* we pass a pointer to this struct to the callback / struct customdata { CURL easy; void ptr; }; static size_t writecb(char buffer, size_t size, size_t nitems, void p) { struct customdata c = (struct customdata )p; const struct curl_ws_frame m = curl_ws_meta(c->easy); printf("flags: %x\\n", m->flags); return 0; } int main(void) { CURL *curl = curl_easy_init(); if(curl) { struct customdata custom; custom.easy = curl; custom.ptr = NULL; curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, writecb); curl_easy_setopt(curl, CURLOPT_WRITEDATA, &custom); curl_easy_perform(curl); } return 0; } .fi .SH AVAILABILITY Added in curl 7.86.0 .SH RETURN VALUE This function returns a pointer to a \fIcurl_ws_frame\fP struct with read\-only information that is valid for this specific callback invocation. If it cannot return this information, or if the function is called in the wrong context, it returns NULL. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_setopt (3), .BR curl_ws_recv (3), .BR curl_ws_send (3), .BR libcurl-ws (3)	4.25 KB	2025-07-08 09:41
📄 curl_ws_recv.3 .\" generated by cd2nroff 0.1 from curl_ws_recv.md .TH curl_ws_recv 3 "2025-06-27" libcurl .SH NAME curl_ws_recv \- receive WebSocket data .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_ws_recv(CURL curl, void buffer, size_t buflen, size_t recv, const struct curl_ws_frame meta); .fi .SH DESCRIPTION Retrieves as much as possible of a received WebSocket frame into the \fIbuffer\fP, but not more than \fIbuflen\fP bytes. \fIrecv\fP is set to the number of bytes actually stored. If the function call is successful, the \fImeta\fP pointer gets set to point to a \fIconst struct curl_ws_frame\fP that contains information about the received data. That struct must not be freed and its contents must not be relied upon anymore once another WebSocket function is called. See \fIcurl_ws_meta(3)\fP for more details on that struct. The application must check \fImeta\->bytesleft\fP to determine whether the complete frame has been received. If more payload is pending, the application must call this function again with an updated \fIbuffer\fP and \fIbuflen\fP to resume receiving. This may for example happen when the data does not fit into the provided buffer or when not all frame data has been delivered over the network yet. If the application wants to read the metadata without consuming any payload, it may call this function with a \fIbuflen\fP of zero. Setting \fIbuffer\fP to a NULL pointer is permitted in this case. Note that frames without payload are consumed by this action. If the received message consists of multiple fragments, the \fICURLWS_CONT\fP bit is set in all frames except the final one. The appropriate \fICURLWS_TEXT\fP or \fICURLWS_BINARY\fP flag is set in every frame, regardless whether it is the first fragment, an intermediate fragment or the final fragment. The application is responsible for reassembling fragmented messages. Special care must be taken to correctly handle control frames (i.e. CLOSE, PING and PONG) arriving in between consecutive fragments of a fragmented TEXT or BINARY message. See \fIcurl_ws_meta(3)\fP for more details on \fICURLWS_CONT\fP. The WebSocket protocol consists of \fImessages\fP that can be delivered over the wire as one or more \fIframes\fP \- but since a frame can be too large to buffer in memory, libcurl may need to deliver partial frames to the application. Fragments, or chunks, of frames. .SH PROTOCOLS This functionality affects ws only .SH EXAMPLE .nf int main(void) { char buffer[256]; size_t offset = 0; CURLcode res = CURLE_OK; CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); /* start HTTPS connection and upgrade to WSS, then return control / curl_easy_perform(curl); / Note: This example neglects fragmented messages. (CURLWS_CONT bit) A real application must handle them appropriately. / while(!res) { size_t recv; const struct curl_ws_frame meta; res = curl_ws_recv(curl, buffer + offset, sizeof(buffer) - offset, &recv, &meta); offset += recv; if(res == CURLE_OK) { if(meta->bytesleft == 0) break; /* finished receiving / if(meta->bytesleft > sizeof(buffer) - offset) res = CURLE_TOO_LARGE; } if(res == CURLE_AGAIN) / in real application: wait for socket here, e.g. using select() */ res = CURLE_OK; } curl_easy_cleanup(curl); return (int)res; } .fi .SH AVAILABILITY Added in curl 7.86.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is closed. Instead of blocking, the function returns \fBCURLE_AGAIN\fP. The correct behavior is then to wait for the socket to signal readability before calling this function again. Any other non\-zero return value indicates an error. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. Returns \fBCURLE_GOT_NOTHING\fP if the associated connection is closed. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_perform (3), .BR curl_easy_setopt (3), .BR curl_ws_send (3), .BR libcurl-ws (3)	4.36 KB	2025-07-08 09:41
📄 curl_ws_send.3 .\" generated by cd2nroff 0.1 from curl_ws_send.md .TH curl_ws_send 3 "2025-06-27" libcurl .SH NAME curl_ws_send \- send WebSocket data .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_ws_send(CURL curl, const void buffer, size_t buflen, size_t sent, curl_off_t fragsize, unsigned int flags); .fi .SH DESCRIPTION Send the specific message chunk over an established WebSocket connection. \fIbuffer\fP must point to a valid memory location containing (at least) \fIbuflen\fP bytes of payload memory. \fIsent\fP is set to the number of payload bytes actually sent. If the return value is \fBCURLE_OK\fP but \fIsent\fP is less than the given \fIbuflen\fP, libcurl was unable to consume the complete payload in a single call. In this case the application must call this function again until all payload is processed. \fIbuffer\fP and \fIbuflen\fP must be updated on every following invocation to only point to the remaining piece of the payload. \fIfragsize\fP should always be set to zero unless a (huge) frame shall be sent using multiple calls with partial content per call explicitly. In that case you must set the \fICURLWS_OFFSET\fP bit and set the \fIfragsize\fP as documented in the section on \fICURLWS_OFFSET\fP below. \fIflags\fP must contain at least one flag indicating the type of the message. To send a fragmented message consisting of multiple frames, additionally set the \fICURLWS_CONT\fP bit in all frames except the final one. The appropriate message type bit should be set in every frame of a fragmented message without exemption. Omitting the message type for continuation frames of a fragmented message is only supported for backwards compatibility and highly discouraged. For more details on the supported flags see below and in \fIcurl_ws_meta(3)\fP. If \fICURLWS_RAW_MODE\fP is enabled in \fICURLOPT_WS_OPTIONS(3)\fP, the \fIflags\fP argument should be set to 0. Warning: while it is possible to invoke this function from a callback, such a call is blocking in this situation, e.g. only returns after all data has been sent or an error is encountered. .SH FLAGS Supports all flags documented in \fIcurl_ws_meta(3)\fP and additionally the following flags. .IP CURLWS_OFFSET The provided data is only a partial frame and there is more coming in a following call to \fIcurl_ws_send()\fP. When sending only a piece of the frame like this, the \fIfragsize\fP must be provided with the total expected frame size in the first call and must be zero in all subsequent calls. .SH PROTOCOLS This functionality affects ws only .SH EXAMPLE .nf #include <string.h> / for strlen / int main(void) { const char buffer = "PAYLOAD"; size_t offset = 0; CURLcode res = CURLE_OK; CURL curl = curl_easy_init(); curl_easy_setopt(curl, CURLOPT_URL, "wss://example.com/"); curl_easy_setopt(curl, CURLOPT_CONNECT_ONLY, 2L); / start HTTPS connection and upgrade to WSS, then return control / curl_easy_perform(curl); while(!res) { size_t sent; res = curl_ws_send(curl, buffer + offset, strlen(buffer) - offset, &sent, 0, CURLWS_TEXT); offset += sent; if(res == CURLE_OK) { if(offset == strlen(buffer)) break; / finished sending / } if(res == CURLE_AGAIN) / in real application: wait for socket here, e.g. using select() */ res = CURLE_OK; } curl_easy_cleanup(curl); return (int)res; } .fi .SH AVAILABILITY Added in curl 7.86.0 .SH RETURN VALUE This function returns a CURLcode indicating success or error. CURLE_OK (0) means everything was OK, non\-zero means an error occurred, see \fIlibcurl\-errors(3)\fP. If \fICURLOPT_ERRORBUFFER(3)\fP was set with \fIcurl_easy_setopt(3)\fP there can be an error message stored in the error buffer when non\-zero is returned. Instead of blocking, the function returns \fBCURLE_AGAIN\fP. The correct behavior is then to wait for the socket to signal readability before calling this function again. Any other non\-zero return value indicates an error. See the \fIlibcurl\-errors(3)\fP man page for the full list with descriptions. .SH SEE ALSO .BR curl_easy_getinfo (3), .BR curl_easy_perform (3), .BR curl_easy_setopt (3), .BR curl_ws_recv (3), .BR libcurl-ws (3)	4.17 KB	2025-07-08 09:41
📄 libcurl-easy.3 .\" generated by cd2nroff 0.1 from libcurl-easy.md .TH libcurl-easy 3 "2025-06-27" libcurl .SH NAME libcurl\-easy \- easy interface overview .SH DESCRIPTION When using libcurl\(aqs "easy" interface you init your session and get a handle (often referred to as an "easy handle"), which you use as input to the easy interface functions you use. Use \fIcurl_easy_init(3)\fP to get the handle. You continue by setting all the options you want in the upcoming transfer, the most important among them is the URL itself (you cannot transfer anything without a specified URL). You might want to set some callbacks as well that are called from the library when data is available etc. For example \fICURLOPT_WRITEFUNCTION(3)\fP. \fIcurl_easy_setopt(3)\fP is used for all this. \fICURLOPT_URL(3)\fP is the only option you really must set, as otherwise there can be no transfer. Another commonly used option is \fICURLOPT_VERBOSE(3)\fP that helps you see what libcurl is doing under the hood, which is useful when debugging for example. The \fIcurl_easy_setopt(3)\fP man page has a full index of the over 300 available options. If you at any point would like to blank all previously set options for a single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also make a clone of an easy handle (with all its set options) using \fIcurl_easy_duphandle(3)\fP. When all is setup, you tell libcurl to perform the transfer using \fIcurl_easy_perform(3)\fP. It performs the entire transfer operation and does not return until it is done (successfully or not). After the transfer has been made, you can set new options and make another transfer, or if you are done, cleanup the session by calling \fIcurl_easy_cleanup(3)\fP. If you want persistent connections, you do not cleanup immediately, but instead run ahead and perform other transfers using the same easy handle. .SH SEE ALSO .BR curl_easy_cleanup (3), .BR curl_easy_init (3), .BR curl_easy_setopt (3), .BR libcurl (3), .BR libcurl-errors (3), .BR libcurl-multi (3)	1.97 KB	2025-07-08 09:41
📄 libcurl-env-dbg.3 .\" generated by cd2nroff 0.1 from libcurl-env-dbg.md .TH libcurl-env-dbg 3 "2025-06-27" libcurl .SH NAME libcurl\-env\-dbg \- environment variables libcurl DEBUGBUILD understands .SH DESCRIPTION This is a set of variables only recognized and used if libcurl was built \&"debug enabled", which should never be true for a library used in production. These variables are intended for internal use only, subject to change and have many effects on the behavior of libcurl. Refer to the source code to determine how exactly they are being used. .IP CURL_ALTSVC_HTTP Bypass the AltSvc HTTPS protocol restriction if this variable exists. .IP CURL_DBG_SOCK_RBLOCK The percentage of recv() calls that should be answered with an EAGAIN at random. For TCP/UNIX sockets. .IP CURL_DBG_SOCK_RMAX The maximum data that shall be received from the network in one recv() call. For TCP/UNIX sockets. This is applied to every recv. Example: \fBCURL_DBG_SOCK_RMAX=400\fP means recv buffer size is limited to a maximum of 400 bytes. .IP CURL_DBG_SOCK_WBLOCK The percentage of send() calls that should be answered with an EAGAIN at random. For TCP/UNIX sockets. .IP CURL_DBG_SOCK_WPARTIAL The percentage of data that shall be written to the network. For TCP/UNIX sockets. This is applied to every send. Example: \fBCURL_DBG_SOCK_WPARTIAL=80\fP means a send with 1000 bytes would only send 800. .IP CURL_DBG_QUIC_WBLOCK The percentage of send() calls that should be answered with EAGAIN at random. QUIC only. .IP CURL_DEBUG Trace logging behavior as an alternative to calling \fIcurl_global_trace(3)\fP. Example: \fBCURL_DEBUG=http/2\fP means trace details about HTTP/2 handling. In the curl command line tool, built with \fI\--enable\-debug\fP, this environment variable adds to arguments like \fI\--verbose\fP, \fI\-vvv\fP. At least a single \fI\-v\fP is needed to make the run emit trace output, but when it does, the contents of \fICURL_DEBUG\fP are added and can override existing options. Example: \fBCURL_DEBUG=tcp,\-http/2 curl \-vv url\fP means trace protocol details, triggered by \fI\-vv\fP, add tracing of TCP in addition and remove tracing of HTTP/2. .IP CURL_DEBUG_SIZE Fake the size returned by CURLINFO_HEADER_SIZE and CURLINFO_REQUEST_SIZE. .IP CURL_DNS_SERVER When built with c\-ares for name resolving, setting this environment variable to \fI[IP:port]\fP makes libcurl use that DNS server instead of the system default. This is used by the curl test suite. .IP CURL_GETHOSTNAME Fake the local machine\(aqs unqualified hostname for NTLM and SMTP. .IP CURL_HSTS_HTTP Bypass the HSTS HTTPS protocol restriction if this variable exists. .IP CURL_FORCETIME A time of 0 is used for AWS signatures and NTLM if this variable exists. .IP CURL_ENTROPY A fixed faked value to use instead of a proper random number so that functions in libcurl that are otherwise getting random outputs can be tested for what they generate. .IP CURL_SMALLREQSEND An alternative size of HTTP data to be sent at a time only if smaller than the current. .IP CURL_SMALLSENDS An alternative size of socket data to be sent at a time only if smaller than the current. .IP CURL_TIME Fake Unix timestamp to use for AltSvc, HSTS and CURLINFO variables that are time related. This variable can also be used to fake the data returned by some CURLINFO variables that are not time\-related (such as CURLINFO_LOCAL_PORT), and in that case the value is not a timestamp. .IP CURL_TRACE LDAP tracing is enabled if this variable exists and its value is 1 or greater. OpenLDAP tracing is separate. Refer to CURL_OPENLDAP_TRACE. .IP CURL_OPENLDAP_TRACE OpenLDAP tracing is enabled if this variable exists and its value is 1 or greater. There is a number of debug levels, refer to \fIopenldap.c\fP comments. .IP CURL_WS_CHUNK_SIZE Used to influence the buffer chunk size used for WebSocket encoding and decoding. .IP CURL_WS_CHUNK_EAGAIN Used to simulate blocking sends after this chunk size for WebSocket connections. .IP CURL_WS_FORCE_ZERO_MASK Used to set the bitmask of all sent WebSocket frames to zero. The value of the environment variable does not matter. .IP CURL_FORBID_REUSE Used to set the CURLOPT_FORBID_REUSE flag on each transfer initiated by the curl command line tool. The value of the environment variable does not matter. .IP CURL_GRACEFUL_SHUTDOWN Make a blocking, graceful shutdown of all remaining connections when a multi handle is destroyed. This implicitly triggers for easy handles that are run via easy_perform. The value of the environment variable gives the shutdown timeout in milliseconds. .IP CURL_H2_STREAM_WIN_MAX Set to a positive 32\-bit number to override the HTTP/2 stream window\(aqs default of 10MB. Used in testing to verify correct window update handling. .SH SEE ALSO .BR libcurl-env (3)	4.67 KB	2025-07-08 09:41
📄 libcurl-env.3 .\" generated by cd2nroff 0.1 from libcurl-env.md .TH libcurl-env 3 "2025-06-27" libcurl .SH NAME libcurl\-env \- environment variables libcurl understands .SH DESCRIPTION libcurl reads and understands a set of environment variables that if set controls and changes behaviors. This is the full list of variables to set and description of what they do. Also note that curl, the command line tool, supports a set of additional environment variables independently of this. .IP [scheme]_proxy When libcurl is given a URL to use in a transfer, it first extracts the scheme part from the URL and checks if there is a given proxy set for that in its corresponding environment variable. A URL like https://example.com makes libcurl use the \fBhttp_proxy\fP variable, while a URL like ftp://example.com uses the \fBftp_proxy\fP variable. These proxy variables are also checked for in their uppercase versions, except the \fBhttp_proxy\fP one which is only used lowercase. Note also that some systems actually have a case insensitive handling of environment variables and then of course \fBHTTP_PROXY\fP still works. An exception exists for the WebSocket \fBws\fP and \fBwss\fP URL schemes, where libcurl first checks \fBws_proxy\fP or \fBwss_proxy\fP but if they are not set, it falls back and tries the http and https versions instead if set. .IP ALL_PROXY This is a setting to set proxy for all URLs, independently of what scheme is being used. Note that the scheme specific variables overrides this one if set. .IP CURL_SSL_BACKEND When libcurl is built to support multiple SSL backends, it selects a specific backend at first use. If no selection is done by the program using libcurl, this variable\(aqs selection is used. Setting a name that is not a built\-in alternative makes libcurl stay with the default. SSL backend names (case\-insensitive): BearSSL, GnuTLS, mbedTLS, OpenSSL, Rustls, Schannel, Secure\-Transport, wolfSSL .IP HOME When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is checked as the primary way to find the "current" home directory in which the .netrc file is likely to exist. .IP USERPROFILE When the netrc feature is used (\fICURLOPT_NETRC(3)\fP), this variable is checked as the secondary way to find the "current" home directory (on Windows only) in which the .netrc file is likely to exist. .IP LOGNAME Username to use when invoking the \fIntlm\-wb\fP tool, if \fINTLMUSER\fP was not set. .IP NO_PROXY This has the same functionality as the \fICURLOPT_NOPROXY(3)\fP option: it gives libcurl a comma\-separated list of hostname patterns for which libcurl should not use a proxy. .IP NTLMUSER Username to use when invoking the \fIntlm\-wb\fP tool. .IP SSLKEYLOGFILE When set and libcurl runs with an SSL backend that supports this feature, libcurl saves SSL secrets into the given filename. Using those SSL secrets, other tools (such as Wireshark) can decrypt the SSL communication and analyze/view the traffic. These secrets and this file might be sensitive. Users are advised to take precautions so that they are not stolen or otherwise inadvertently revealed. .IP USER Username to use when invoking the \fIntlm\-wb\fP tool, if \fINTLMUSER\fP and \fILOGNAME\fP were not set. .SH Debug Variables Debug variables are intended for internal use and are documented in \fIlibcurl\-env\-dbg(3)\fP. .SH SEE ALSO .BR libcurl-env-dbg (3)	3.3 KB	2025-07-08 09:41
📄 libcurl-errors.3 .\" generated by cd2nroff 0.1 from libcurl-errors.md .TH libcurl-errors 3 "2025-06-27" libcurl .SH NAME libcurl\-errors \- error codes in libcurl .SH DESCRIPTION This man page includes most, if not all, available error codes in libcurl. Why they occur and possibly what you can do to fix the problem are also included. .SH CURLcode Almost all "easy" interface functions return a CURLcode error code. No matter what, using the \fIcurl_easy_setopt(3)\fP option \fICURLOPT_ERRORBUFFER(3)\fP is a good idea as it gives you a human readable error string that may offer more details about the cause of the error than just the error code. \fIcurl_easy_strerror(3)\fP can be called to get an error string from a given CURLcode number. CURLcode is one of the following: .IP "CURLE_OK (0)" All fine. Proceed as usual. .IP "CURLE_UNSUPPORTED_PROTOCOL (1)" The URL you passed to libcurl used a protocol that this libcurl does not support. The support might be a compile\-time option that you did not use, it can be a misspelled protocol string or just a protocol libcurl has no code for. .IP "CURLE_FAILED_INIT (2)" Early initialization code failed. This is likely to be an internal error or problem, or a resource problem where something fundamental could not 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 into 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)" Could not resolve proxy. The given proxy host could not be resolved. .IP "CURLE_COULDNT_RESOLVE_HOST (6)" Could not resolve host. The given remote host was not resolved. .IP "CURLE_COULDNT_CONNECT (7)" Failed to connect() to host or proxy. .IP "CURLE_WEIRD_SERVER_REPLY (8)" The server sent data libcurl could not parse. This error code was known as \fICURLE_FTP_WEIRD_SERVER_REPLY\fP before 7.51.0. .IP "CURLE_REMOTE_ACCESS_DENIED (9)" We were denied access to the resource given in the URL. For FTP, this occurs while trying to change to the remote directory. .IP "CURLE_FTP_ACCEPT_FAILED (10)" While waiting for the server to connect back when an active FTP session is used, an error code was sent over the control connection or similar. .IP "CURLE_FTP_WEIRD_PASS_REPLY (11)" After having sent the FTP password to the server, libcurl expects a proper reply. This error code indicates that an unexpected code was returned. .IP "CURLE_FTP_ACCEPT_TIMEOUT (12)" During an active FTP session while waiting for the server to connect, the \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired. .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)" libcurl failed to get a sensible result back from the server as a response to either a PASV or an EPSV command. The server is flawed. .IP "CURLE_FTP_WEIRD_227_FORMAT (14)" FTP servers return a 227\-line as a response to a PASV command. If libcurl fails to parse that line, this return code is passed back. .IP "CURLE_FTP_CANT_GET_HOST (15)" An internal failure to lookup the host used for the new connection. .IP "CURLE_HTTP2 (16)" A problem was detected in the HTTP2 framing layer. This is somewhat generic and can be one out of several problems, see the error buffer for details. .IP "CURLE_FTP_COULDNT_SET_TYPE (17)" Received an error when trying to set the transfer mode to binary or ASCII. .IP "CURLE_PARTIAL_FILE (18)" A file transfer was shorter or larger than expected. This happens when the server first reports an expected transfer size, and then delivers data that does not match the previously given size. .IP "CURLE_FTP_COULDNT_RETR_FILE (19)" This was either a weird reply to a \(aqRETR\(aq command or a zero byte transfer complete. .IP "Obsolete error (20)" Not used in modern versions. .IP "CURLE_QUOTE_ERROR (21)" When sending custom "QUOTE" commands to the remote server, one of the commands returned an error code that was 400 or higher (for FTP) or otherwise indicated unsuccessful completion of the command. .IP "CURLE_HTTP_RETURNED_ERROR (22)" This is returned if \fICURLOPT_FAILONERROR(3)\fP is set TRUE and the HTTP server returns an error code that is >= 400. .IP "CURLE_WRITE_ERROR (23)" An error occurred when writing received data to a local file, or an error was returned to libcurl from a write callback. .IP "Obsolete error (24)" Not used in modern versions. .IP "CURLE_UPLOAD_FAILED (25)" Failed starting the upload. For FTP, the server typically denied the STOR command. The error buffer usually contains the server\(aqs explanation for this. .IP "CURLE_READ_ERROR (26)" There was a problem reading a local file or an error returned by the read callback. .IP "CURLE_OUT_OF_MEMORY (27)" A memory allocation request failed. This is serious badness and things are severely screwed up if this ever occurs. .IP "CURLE_OPERATION_TIMEDOUT (28)" Operation timeout. The specified time\-out period was reached according to the conditions. .IP "Obsolete error (29)" Not used in modern versions. .IP "CURLE_FTP_PORT_FAILED (30)" The FTP PORT command returned error. This mostly happens when you have not specified a good enough address for libcurl to use. See \fICURLOPT_FTPPORT(3)\fP. .IP "CURLE_FTP_COULDNT_USE_REST (31)" The FTP REST command returned error. This should never happen if the server is sane. .IP "Obsolete error (32)" Not used in modern versions. .IP "CURLE_RANGE_ERROR (33)" The server does not support or accept range requests. .IP "Obsolete error (34)" Not used since 7.56.0. .IP "CURLE_SSL_CONNECT_ERROR (35)" A problem occurred somewhere in the SSL/TLS handshake. You really want the error buffer and read the message there as it pinpoints the problem slightly more. Could be certificates (file formats, paths, permissions), passwords, and others. .IP "CURLE_BAD_DOWNLOAD_RESUME (36)" The download could not be resumed because the specified offset was out of the file boundary. .IP "CURLE_FILE_COULDNT_READ_FILE (37)" A file given with FILE:// could not be opened. Most likely because the file path does not identify an existing file. Did you check file permissions? .IP "CURLE_LDAP_CANNOT_BIND (38)" LDAP cannot bind. LDAP bind operation failed. .IP "CURLE_LDAP_SEARCH_FAILED (39)" LDAP search failed. .IP "Obsolete error (40)" Not used in modern versions. .IP "Obsolete error (41)" Not used since 7.53.0. .IP "CURLE_ABORTED_BY_CALLBACK (42)" Aborted by callback. A callback returned "abort" to libcurl. .IP "CURLE_BAD_FUNCTION_ARGUMENT (43)" A function was called with a bad parameter. .IP "Obsolete error (44)" Not used in modern versions. .IP "CURLE_INTERFACE_FAILED (45)" Interface error. A specified outgoing interface could not be used. Set which interface to use for outgoing connections\(aq source IP address with \fICURLOPT_INTERFACE(3)\fP. .IP "Obsolete error (46)" Not used in modern versions. .IP "CURLE_TOO_MANY_REDIRECTS (47)" Too many redirects. When following redirects, libcurl hit the maximum amount. Set your limit with \fICURLOPT_MAXREDIRS(3)\fP. .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_SETOPT_OPTION_SYNTAX (49)" An option passed in to a setopt was wrongly formatted. See error message for details about what option. .IP "Obsolete errors (50-51)" Not used in modern versions. .IP "CURLE_GOT_NOTHING (52)" Nothing was returned from the server, and under the circumstances, getting nothing is considered an error. .IP "CURLE_SSL_ENGINE_NOTFOUND (53)" The specified crypto engine was not found. .IP "CURLE_SSL_ENGINE_SETFAILED (54)" Failed setting the selected SSL crypto engine as default. .IP "CURLE_SEND_ERROR (55)" Failed sending network data. .IP "CURLE_RECV_ERROR (56)" Failure with receiving network data. .IP "Obsolete error (57)" Not used in modern versions. .IP "CURLE_SSL_CERTPROBLEM (58)" problem with the local client certificate. .IP "CURLE_SSL_CIPHER (59)" Could not use specified cipher. .IP "CURLE_PEER_FAILED_VERIFICATION (60)" The remote server\(aqs SSL certificate or SSH fingerprint was deemed not OK. This error code has been unified with CURLE_SSL_CACERT since 7.62.0. Its previous value was 51. .IP "CURLE_BAD_CONTENT_ENCODING (61)" Unrecognized transfer encoding. .IP "Obsolete error (62)" Not used in modern versions. .IP "CURLE_FILESIZE_EXCEEDED (63)" Maximum file size exceeded. .IP "CURLE_USE_SSL_FAILED (64)" Requested FTP SSL level failed. .IP "CURLE_SEND_FAIL_REWIND (65)" When doing a send operation curl had to rewind the data to retransmit, but the rewinding operation failed. .IP "CURLE_SSL_ENGINE_INITFAILED (66)" Initiating the SSL Engine failed. .IP "CURLE_LOGIN_DENIED (67)" The remote server denied curl to login (Added in 7.13.1) .IP "CURLE_TFTP_NOTFOUND (68)" File not found on TFTP server. .IP "CURLE_TFTP_PERM (69)" Permission problem on TFTP server. .IP "CURLE_REMOTE_DISK_FULL (70)" Out of disk space on the server. .IP "CURLE_TFTP_ILLEGAL (71)" Illegal TFTP operation. .IP "CURLE_TFTP_UNKNOWNID (72)" Unknown TFTP transfer ID. .IP "CURLE_REMOTE_FILE_EXISTS (73)" File already exists and is not overwritten. .IP "CURLE_TFTP_NOSUCHUSER (74)" This error should never be returned by a properly functioning TFTP server. .IP "Obsolete error (75-76)" Not used in modern versions. .IP "CURLE_SSL_CACERT_BADFILE (77)" Problem with reading the SSL CA cert (path? access rights?) .IP "CURLE_REMOTE_FILE_NOT_FOUND (78)" The resource referenced in the URL does not exist. .IP "CURLE_SSH (79)" An unspecified error occurred during the SSH session. .IP "CURLE_SSL_SHUTDOWN_FAILED (80)" Failed to shut down the SSL connection. .IP "CURLE_AGAIN (81)" Socket is not ready for send/recv. Wait until it is ready and try again. This return code is only returned from \fIcurl_easy_recv(3)\fP and \fIcurl_easy_send(3)\fP (Added in 7.18.2) .IP "CURLE_SSL_CRL_BADFILE (82)" Failed to load CRL file (Added in 7.19.0) .IP "CURLE_SSL_ISSUER_ERROR (83)" Issuer check failed (Added in 7.19.0) .IP "CURLE_FTP_PRET_FAILED (84)" The FTP server does not understand the PRET command at all or does not support the given argument. Be careful when using \fICURLOPT_CUSTOMREQUEST(3)\fP, a custom LIST command is sent with the PRET command before PASV as well. (Added in 7.20.0) .IP "CURLE_RTSP_CSEQ_ERROR (85)" Mismatch of RTSP CSeq numbers. .IP "CURLE_RTSP_SESSION_ERROR (86)" Mismatch of RTSP Session Identifiers. .IP "CURLE_FTP_BAD_FILE_LIST (87)" Unable to parse FTP file list (during FTP wildcard downloading). .IP "CURLE_CHUNK_FAILED (88)" Chunk callback reported error. .IP "CURLE_NO_CONNECTION_AVAILABLE (89)" (For internal use only, is never returned by libcurl) No connection available, the session is queued. (added in 7.30.0) .IP "CURLE_SSL_PINNEDPUBKEYNOTMATCH (90)" Failed to match the pinned key specified with \fICURLOPT_PINNEDPUBLICKEY(3)\fP. .IP "CURLE_SSL_INVALIDCERTSTATUS (91)" Status returned failure when asked with \fICURLOPT_SSL_VERIFYSTATUS(3)\fP. .IP "CURLE_HTTP2_STREAM (92)" Stream error in the HTTP/2 framing layer. .IP "CURLE_RECURSIVE_API_CALL (93)" An API function was called from inside a callback. .IP "CURLE_AUTH_ERROR (94)" An authentication function returned an error. .IP "CURLE_HTTP3 (95)" A problem was detected in the HTTP/3 layer. This is somewhat generic and can be one out of several problems, see the error buffer for details. .IP "CURLE_QUIC_CONNECT_ERROR (96)" QUIC connection error. This error may be caused by an SSL library error. QUIC is the protocol used for HTTP/3 transfers. .IP "CURLE_PROXY (97)" Proxy handshake error. \fICURLINFO_PROXY_ERROR(3)\fP provides extra details on the specific problem. .IP "CURLE_SSL_CLIENTCERT (98)" SSL Client Certificate required. .IP "CURLE_UNRECOVERABLE_POLL (99)" An internal call to poll() or select() returned error that is not recoverable. .IP "CURLE_TOO_LARGE (100)" A value or data field grew larger than allowed. .IP "CURLE_ECH_REQUIRED (101)"" ECH was attempted but failed. .SH CURLMcode This is the generic return code used by functions in the libcurl multi interface. Also consider \fIcurl_multi_strerror(3)\fP. .IP "CURLM_CALL_MULTI_PERFORM (-1)" This is not really an error. It means you should call \fIcurl_multi_perform(3)\fP again without doing select() or similar in between. Before version 7.20.0 (released on February 9 2010) this could be returned by \fIcurl_multi_perform(3)\fP, but in later versions this return code is never used. .IP "CURLM_OK (0)" Things are fine. .IP "CURLM_BAD_HANDLE (1)" The passed\-in handle is not a valid \fICURLM\fP handle. .IP "CURLM_BAD_EASY_HANDLE (2)" An easy handle was not good/valid. It could mean that it is not an easy handle at all, or possibly that the handle already is in use by this or another multi handle. .IP "CURLM_OUT_OF_MEMORY (3)" You are doomed. .IP "CURLM_INTERNAL_ERROR (4)" This can only be returned if libcurl bugs. Please report it to us. .IP "CURLM_BAD_SOCKET (5)" The passed\-in socket is not a valid one that libcurl already knows about. (Added in 7.15.4) .IP "CURLM_UNKNOWN_OPTION (6)" curl_multi_setopt() with unsupported option (Added in 7.15.4) .IP "CURLM_ADDED_ALREADY (7)" An easy handle already added to a multi handle was attempted to get added a second time. (Added in 7.32.1) .IP "CURLM_RECURSIVE_API_CALL (8)" An API function was called from inside a callback. .IP "CURLM_WAKEUP_FAILURE (9)" Wake up is unavailable or failed. .IP "CURLM_BAD_FUNCTION_ARGUMENT (10)" A function was called with a bad parameter. .IP "CURLM_ABORTED_BY_CALLBACK (11)" A multi handle callback returned error. .IP "CURLM_UNRECOVERABLE_POLL (12)" An internal call to poll() or select() returned error that is not recoverable. .SH CURLSHcode The "share" interface returns a \fBCURLSHcode\fP to indicate when an error has occurred. Also consider \fIcurl_share_strerror(3)\fP. .IP "CURLSHE_OK (0)" All fine. Proceed as usual. .IP "CURLSHE_BAD_OPTION (1)" An invalid option was passed to the function. .IP "CURLSHE_IN_USE (2)" The share object is currently in use. .IP "CURLSHE_INVALID (3)" An invalid share object was passed to the function. .IP "CURLSHE_NOMEM (4)" Not enough memory was available. (Added in 7.12.0) .IP "CURLSHE_NOT_BUILT_IN (5)" The requested sharing could not be done because the library you use do not have that particular feature enabled. (Added in 7.23.0) .SH CURLUcode The URL interface returns a \fICURLUcode\fP to indicate when an error has occurred. Also consider \fIcurl_url_strerror(3)\fP. .IP "CURLUE_OK (0)" All fine. Proceed as usual. .IP "CURLUE_BAD_HANDLE (1)" An invalid URL handle was passed as argument. .IP "CURLUE_BAD_PARTPOINTER (2)" An invalid \(aqpart\(aq argument was passed as argument. .IP "CURLUE_MALFORMED_INPUT (3)" A malformed input was passed to a URL API function. .IP "CURLUE_BAD_PORT_NUMBER (4)" The port number was not a decimal number between 0 and 65535. .IP "CURLUE_UNSUPPORTED_SCHEME (5)" This libcurl build does not support the given URL scheme. .IP "CURLUE_URLDECODE (6)" URL decode error, most likely because of rubbish in the input. .IP "CURLUE_OUT_OF_MEMORY (7)" A memory function failed. .IP "CURLUE_USER_NOT_ALLOWED (8)" Credentials was passed in the URL when prohibited. .IP "CURLUE_UNKNOWN_PART (9)" An unknown part ID was passed to a URL API function. .IP "CURLUE_NO_SCHEME (10)" There is no scheme part in the URL. .IP "CURLUE_NO_USER (11)" There is no user part in the URL. .IP "CURLUE_NO_PASSWORD (12)" There is no password part in the URL. .IP "CURLUE_NO_OPTIONS (13)" There is no options part in the URL. .IP "CURLUE_NO_HOST (14)" There is no host part in the URL. .IP "CURLUE_NO_PORT (15)" There is no port part in the URL. .IP "CURLUE_NO_QUERY (16)" There is no query part in the URL. .IP "CURLUE_NO_FRAGMENT (17)" There is no fragment part in the URL. .IP "CURLUE_NO_ZONEID (18)" There is no zone id set in the URL. .IP "CURLUE_BAD_FILE_URL (19)" The file:// URL is invalid. .IP "CURLUE_BAD_FRAGMENT (20)" The fragment part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_HOSTNAME (21)" The hostname contained bad or invalid characters. .IP "CURLUE_BAD_IPV6 (22)" The IPv6 address hostname contained bad or invalid characters. .IP "CURLUE_BAD_LOGIN (23)" The login part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_PASSWORD (24)" The password part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_PATH (25)" The path part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_QUERY (26)" The query part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_SCHEME (27)" The scheme part of the URL contained bad or invalid characters. .IP "CURLUE_BAD_SLASHES (28)" The URL contained an invalid number of slashes. .IP "CURLUE_BAD_USER (29)" The user part of the URL contained bad or invalid characters. .IP "CURLUE_LACKS_IDN (30)" libcurl lacks IDN support. .IP "CURLUE_TOO_LARGE (31)" A value or data field is larger than allowed. .SH CURLHcode The header interface returns a \fICURLHcode\fP to indicate when an error has occurred. .IP "CURLHE_OK (0)" All fine. Proceed as usual. .IP "CURLHE_BADINDEX (1)" There is no header with the requested index. .IP "CURLHE_MISSING (2)" No such header exists. .IP "CURLHE_NOHEADERS (3)" No headers at all have been recorded. .IP "CURLHE_NOREQUEST (4)" There was no such request number. .IP "CURLHE_OUT_OF_MEMORY (5)" Out of resources .IP "CURLHE_BAD_ARGUMENT (6)" One or more of the given arguments are bad. .IP "CURLHE_NOT_BUILT_IN (7)" HTTP support or the header API has been disabled in the build. .SH SEE ALSO .BR CURLOPT_DEBUGFUNCTION (3), .BR CURLOPT_ERRORBUFFER (3), .BR CURLOPT_VERBOSE (3), .BR curl_easy_strerror (3), .BR curl_multi_strerror (3), .BR curl_share_strerror (3), .BR curl_url_strerror (3)	17.58 KB	2025-07-08 09:41
📄 libcurl-multi.3 .\" generated by cd2nroff 0.1 from libcurl-multi.md .TH libcurl-multi 3 "2025-06-27" libcurl .SH NAME libcurl\-multi \- how to use the multi interface .SH DESCRIPTION This is an overview on how to use the libcurl multi interface in your C programs. There are specific man pages for each function mentioned in here. There is also the \fIlibcurl\-tutorial(3)\fP man page for a complete tutorial to programming with libcurl and the \fIlibcurl\-easy(3)\fP man page for an overview of the libcurl easy interface. All functions in the multi interface are prefixed with curl_multi. .SH OBJECTIVES The multi interface offers several abilities that the easy interface does not. They are mainly: 1. Enable a "pull" interface. The application that uses libcurl decides where and when to ask libcurl to get/send data. 2. Enable multiple simultaneous transfers in the same thread without making it complicated for the application. 3. Enable the application to wait for action on its own file descriptors and curl\(aqs file descriptors simultaneously. 4. Enable event\-based handling and scaling transfers up to and beyond thousands of parallel connections. .SH ONE MULTI HANDLE MANY EASY HANDLES To use the multi interface, you must first create a \(aqmulti handle\(aq with \fIcurl_multi_init(3)\fP. This handle is then used as input to all further curl_multi_* functions. With a multi handle and the multi interface you can do several simultaneous transfers in parallel. Each single transfer is built up around an easy handle. You create all the easy handles you need, and setup the appropriate options for each easy handle using \fIcurl_easy_setopt(3)\fP. There are two flavors of the multi interface, the select() oriented one and the event based one we call multi_socket. You benefit from reading through the description of both versions to fully understand how they work and differentiate. We start out with the select() oriented version. When an easy handle is setup and ready for transfer, then instead of using \fIcurl_easy_perform(3)\fP like when using the easy interface for transfers, you should add the easy handle to the multi handle with \fIcurl_multi_add_handle(3)\fP. You can add more easy handles to a multi handle at any point, even if other transfers are already running. Should you change your mind, the easy handle is again removed from the multi stack using \fIcurl_multi_remove_handle(3)\fP. Once removed from the multi handle, you can again use other easy interface functions like \fIcurl_easy_perform(3)\fP on the handle or whatever you think is necessary. You can remove handles at any point during transfers. Adding the easy handle to the multi handle does not start the transfer. Remember that one of the main ideas with this interface is to let your application drive. You drive the transfers by invoking \fIcurl_multi_perform(3)\fP. libcurl then transfers data if there is anything available to transfer. It uses the callbacks and everything else you have setup in the individual easy handles. It transfers data on all current transfers in the multi stack that are ready to transfer anything. It may be all, it may be none. When there is nothing more to do for now, it returns back to the calling application. Your application extracts info from libcurl about when it would like to get invoked to transfer data or do other work. The most convenient way is to use \fIcurl_multi_poll(3)\fP that helps you wait until the application should call libcurl again. The older API to accomplish the same thing is \fIcurl_multi_fdset(3)\fP that extracts \fIfd_sets\fP from libcurl to use in select() or poll() calls in order to get to know when the transfers in the multi stack might need attention. Both these APIs allow for your program to wait for input on your own private file descriptors at the same time. \fIcurl_multi_timeout(3)\fP also helps you with providing a suitable timeout period for your select() calls. \fIcurl_multi_perform(3)\fP stores the number of still running transfers in one of its input arguments, and by reading that you can figure out when all the transfers in the multi handles are done. \(aqdone\(aq does not mean successful. One or more of the transfers may have failed. To get information about completed transfers, to figure out success or not and similar, \fIcurl_multi_info_read(3)\fP should be called. It can return a message about a current or previous transfer. Repeated invokes of the function get more messages until the message queue is empty. The information you receive there includes an easy handle pointer which you may use to identify which easy handle the information regards. When a single transfer is completed, the easy handle is still left added to the multi stack. You need to first remove the easy handle with \fIcurl_multi_remove_handle(3)\fP and then close it with \fIcurl_easy_cleanup(3)\fP, or possibly set new options to it and add it again with \fIcurl_multi_add_handle(3)\fP to start another transfer. When all transfers in the multi stack are done, close the multi handle with \fIcurl_multi_cleanup(3)\fP. Be careful and please note that you \fBMUST\fP invoke separate \fIcurl_easy_cleanup(3)\fP calls for every single easy handle to clean them up properly. If you want to reuse an easy handle that was added to the multi handle for transfer, you must first remove it from the multi stack and then re\-add it again (possibly after having altered some options at your own choice). .SH MULTI_SOCKET \fIcurl_multi_socket_action(3)\fP function offers a way for applications to not only avoid being forced to use select(), but it also offers a much more high\-performance API that makes a significant difference for applications using large numbers of simultaneous connections. \fIcurl_multi_socket_action(3)\fP is then used instead of \fIcurl_multi_perform(3)\fP. When using this API, you add easy handles to the multi handle just as with the normal multi interface. Then you also set two callbacks with the \fICURLMOPT_SOCKETFUNCTION(3)\fP and \fICURLMOPT_TIMERFUNCTION(3)\fP options to \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl calls with information about what sockets to wait for, and for what activity, and what the current timeout time is \- if that expires libcurl should be notified. The multi_socket API is designed to inform your application about which sockets libcurl is currently using and for what activities (read and/or write) on those sockets your application is expected to wait for. Your application must make sure to receive all sockets informed about in the \fICURLMOPT_SOCKETFUNCTION(3)\fP callback and make sure it reacts on the given activity on them. When a socket has the given activity, you call \fIcurl_multi_socket_action(3)\fP specifying which socket and action there are. The \fICURLMOPT_TIMERFUNCTION(3)\fP callback is called to set a timeout. When that timeout expires, your application should call the \fIcurl_multi_socket_action(3)\fP function saying it was due to a timeout. This API is typically used with an event\-driven underlying functionality (like libevent, libev, kqueue, epoll or similar) with which the application \&"subscribes" on socket changes. This allows applications and libcurl to much better scale upward and beyond thousands of simultaneous transfers without losing performance. When you have added your initial set of handles, you call \fIcurl_multi_socket_action(3)\fP with CURL_SOCKET_TIMEOUT set in the \fIsockfd\fP argument, and you get callbacks invoked that set you up and you then continue to call \fIcurl_multi_socket_action(3)\fP accordingly when you get activity on the sockets you have been asked to wait on, or if the timeout timer expires. You can poll \fIcurl_multi_info_read(3)\fP to see if any transfer has completed, as it then has a message saying so. .SH BLOCKING A few areas in the code are still using blocking code, even when used from the multi interface. While we certainly want and intend for these to get fixed in the future, you should be aware of the following current restrictions: .nf - Name resolves unless the c-ares or threaded-resolver backends are used - file:// transfers - TELNET transfers .fi .SH SEE ALSO .BR libcurl (3), .BR libcurl-easy (3), .BR libcurl-errors (3)	8.09 KB	2025-07-08 09:41
📄 libcurl-security.3 .\" generated by cd2nroff 0.1 from libcurl-security.md .TH libcurl-security 3 "2025-06-27" libcurl .SH NAME libcurl\-security \- security considerations when using libcurl .SH Security The libcurl project takes security seriously. The library is written with caution and precautions are taken to mitigate many kinds of risks encountered while operating with potentially malicious servers on the Internet. It is a powerful library, however, which allows application writers to make trade\-offs between ease of writing and exposure to potential risky operations. If used the right way, you can use libcurl to transfer data pretty safely. Many applications are used in closed networks where users and servers can (possibly) be trusted, but many others are used on arbitrary servers and are fed input from potentially untrusted users. Following is a discussion about some risks in the ways in which applications commonly use libcurl and potential mitigations of those risks. It is not comprehensive, but shows classes of attacks that robust applications should consider. The Common Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for many of these and similar types of weaknesses of which application writers should be aware. .SH Command Lines If you use a command line tool (such as curl) that uses libcurl, and you give options to the tool on the command line those options can get read by other users of your system when they use \fIps\fP or other tools to list currently running processes. To avoid these problems, never feed sensitive things to programs using command line options. Write them to a protected file and use the \-K option to avoid this. .SH .netrc \&.netrc is a pretty handy file/feature that allows you to login quickly and automatically to frequently visited sites. The file contains passwords in clear text and is a real security risk. In some cases, your .netrc is also stored in a home directory that is NFS mounted or used on another network based file system, so the clear text password flies through your network every time anyone reads that file. For applications that enable .netrc use, a user who manage to set the right URL might then be possible to pass on passwords. To avoid these problems, do not use .netrc files and never store passwords in plain text anywhere. .SH Clear Text Passwords Many of the protocols libcurl supports send name and password unencrypted as clear text (HTTP Basic authentication, FTP, TELNET etc). It is easy for anyone on your network or a network nearby yours to just fire up a network analyzer tool and eavesdrop on your passwords. Do not let the fact that HTTP Basic uses base64 encoded passwords fool you. They may not look readable at a first glance, but they are easily "deciphered" by anyone within seconds. To avoid this problem, use an authentication mechanism or other protocol that does not let snoopers see your password: Digest, CRAM\-MD5, Kerberos, SPNEGO or NTLM authentication. Or even better: use authenticated protocols that protect the entire connection and everything sent over it. .SH Unauthenticated Connections Protocols that do not have any form of cryptographic authentication cannot with any certainty know that they communicate with the right remote server. If your application is using a fixed scheme or fixed hostname, it is not safe as long as the connection is unauthenticated. There can be a man\-in\-the\-middle or in fact the whole server might have been replaced by an evil actor. Unauthenticated protocols are unsafe. The data that comes back to curl may have been injected by an attacker. The data that curl sends might be modified before it reaches the intended server. If it even reaches the intended server at all. Remedies: .IP "Restrict operations to authenticated transfers" Use authenticated protocols protected with HTTPS or SSH. .IP "Make sure the server's certificate etc is verified" Never ever switch off certificate verification. .SH Redirects The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP redirects sent by a remote server. These redirects can refer to any kind of URL, not just HTTP. libcurl restricts the protocols allowed to be used in redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are enabled by default. Applications may opt to restrict that set further. A redirect to a file: URL would cause the libcurl to read (or write) arbitrary files from the local filesystem. If the application returns the data back to the user (as would happen in some kinds of CGI scripts), an attacker could leverage this to read otherwise forbidden data (e.g. \fBfile://localhost/etc/passwd\fP). If authentication credentials are stored in the ~/.netrc file, or Kerberos is in use, any other URL type (not just file:) that requires authentication is also at risk. A redirect such as \fBftp://some\-internal\-server/private\-file\fP would then return data even when the server is password protected. In the same way, if an unencrypted SSH private key has been configured for the user running the libcurl application, SCP: or SFTP: URLs could access password or private\-key protected resources, e.g. \fBsftp://user@some\-internal\-server/etc/passwd\fP The \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP and \fICURLOPT_NETRC(3)\fP options can be used to mitigate against this kind of attack. A redirect can also specify a location available only on the machine running libcurl, including servers hidden behind a firewall from the attacker. E.g. \fBhttp://127.0.0.1/\fP or \fBhttp://intranet/delete\-stuff.cgi?delete=all\fP or \fBtftp://bootp\-server/pc\-config\-data\fP Applications can mitigate against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP enabled but set \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP and install a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP callback function in which addresses are sanitized before use. .SH CRLF in Headers For all options in libcurl which specify headers, including but not limited to \fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_PROXYHEADER(3)\fP, \fICURLOPT_COOKIE(3)\fP, \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_REFERER(3)\fP and \fICURLOPT_RANGE(3)\fP, libcurl sends the headers as\-is and does not apply any special sanitation or normalization to them. If you allow untrusted user input into these options without sanitizing CRLF sequences in them, someone malicious may be able to modify the request in a way you did not intend such as injecting new headers. .SH Local Resources A user who can control the DNS server of a domain being passed in within a URL can change the address of the host to a local, private address which a server\-side libcurl\-using application could then use. E.g. the innocuous URL \fBhttp://fuzzybunnies.example.com/\fP could actually resolve to the IP address of a server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can mitigate against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP or \fICURLOPT_PREREQFUNCTION(3)\fP and checking the address before a connection. All the malicious scenarios regarding redirected URLs apply just as well to non\-redirected URLs, if the user is allowed to specify an arbitrary URL that could point to a private resource. For example, a web app providing a translation service might happily translate \fBfile://localhost/etc/passwd\fP and display the result. Applications can mitigate against this with the \fICURLOPT_PROTOCOLS_STR(3)\fP option as well as by similar mitigation techniques for redirections. A malicious FTP server could in response to the PASV command return an IP address and port number for a server local to the app running libcurl but behind a firewall. Applications can mitigate against this by using the \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP. Local servers sometimes assume local access comes from friends and trusted users. An application that expects https://example.com/file_to_read that and instead gets http://192.168.0.1/my_router_config might print a file that would otherwise be protected by the firewall. Allowing your application to connect to local hosts, be it the same machine that runs the application or a machine on the same local network, might be possible to exploit by an attacker who then perhaps can "port\-scan" the particular hosts \- depending on how the application and servers acts. .SH IPv4 Addresses Some users might be tempted to filter access to local resources or similar based on numerical IPv4 addresses used in URLs. This is a bad and error\-prone idea because of the many different ways a numerical IPv4 address can be specified and libcurl accepts: one to four dot\-separated fields using one of or a mix of decimal, octal or hexadecimal encoding. .SH IPv6 Addresses libcurl handles IPv6 addresses transparently and just as easily as IPv4 addresses. That means that a sanitizing function that filters out addresses like 127.0.0.1 is not sufficient \- the equivalent IPv6 addresses \fB::1\fP, \fB::\fP, \fB0:00::0:1\fP, \fB::127.0.0.1\fP and \fB::ffff:7f00:1\fP supplied somehow by an attacker would all bypass a naive filter and could allow access to undesired local resources. IPv6 also has special address blocks like link\-local and site\-local that generally should not be accessed by a server\-side libcurl\-using application. A poorly configured firewall installed in a data center, organization or server may also be configured to limit IPv4 connections but leave IPv6 connections wide open. In some cases, setting \fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved addresses to IPv4 only and bypass these issues. .SH Uploads When uploading, a redirect can cause a local (or remote) file to be overwritten. Applications must not allow any unsanitized URL to be passed in for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on uploads. Instead, the applications should consider handling redirects itself, sanitizing each URL first. .SH Authentication Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication information to be sent to an unknown second server. Applications can mitigate against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing where necessary. Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in username and password being sent in clear text to an HTTP server. Instead, use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the network, or else fail the request. Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in username and password being sent in clear text to an FTP server. Instead, use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else fail the request. .SH Cookies If cookies are enabled and cached, then a user could craft a URL which performs some malicious action to a site whose authentication is already stored in a cookie. E.g. \fBhttp://mail.example.com/delete\-stuff.cgi?delete=all\fP Applications can mitigate against this by disabling cookies or clearing them between requests. .SH Dangerous SCP URLs SCP URLs can contain raw commands within the scp: URL, which is a side effect of how the SCP protocol is designed. E.g. .nf scp://user:pass@host/a;date >/tmp/test; .fi Applications must not allow unsanitized SCP: URLs to be passed in for downloads. .SH file:// By default curl and libcurl support file:// URLs. Such a URL is always an access, or attempted access, to a local resource. If your application wants to avoid that, keep control of what URLs to use and/or prevent curl/libcurl from using the protocol. By default, libcurl prohibits redirects to file:// URLs. .SH Warning: file:// on Windows The Windows operating system tries automatically, and without any way for applications to disable it, to establish a connection to another host over the network and access it (over SMB or other protocols), if only the correct file path is accessed. When first realizing this, the curl team tried to filter out such attempts in order to protect applications for inadvertent probes of for example internal networks etc. This resulted in CVE\-2019\-15601 and the associated security fix. However, we have since been made aware of the fact that the previous fix was far from adequate as there are several other ways to accomplish more or less the same thing: accessing a remote host over the network instead of the local file system. The conclusion we have come to is that this is a weakness or feature in the Windows operating system itself, that we as an application cannot safely protect users against. It would just be a whack\-a\-mole race we do not want to participate in. There are too many ways to do it and there is no knob we can use to turn off the practice. If you use curl or libcurl on Windows (any version), disable the use of the FILE protocol in curl or be prepared that accesses to a range of "magic paths" potentially make your system access other hosts on your network. curl cannot protect you against this. .SH What if the user can set the URL Applications may find it tempting to let users set the URL that it can work on. That is probably fine, but opens up for mischief and trickery that you as an application author may want to address or take precautions against. If your curl\-using script allow a custom URL do you also, perhaps unintentionally, allow the user to pass other options to the curl command line if creative use of special characters are applied? If the user can set the URL, the user can also specify the scheme part to other protocols that you did not intend for users to use and perhaps did not consider. curl supports over 20 different URL schemes. "http://" might be what you thought, "ftp://" or "imap://" might be what the user gives your application. Also, cross\-protocol operations might be done by using a particular scheme in the URL but point to a server doing a different protocol on a non\-standard port. Remedies: .IP "Use --proto" curl command lines can use \fI\--proto\fP to limit what URL schemes it accepts .IP "Use CURLOPT_PROTOCOLS_STR" libcurl programs can use \fICURLOPT_PROTOCOLS_STR(3)\fP to limit what URL schemes it accepts .IP "consider not allowing the user to set the full URL" Maybe just let the user provide data for parts of it? Or maybe filter input to only allow specific choices? .SH RFC 3986 vs WHATWG URL curl supports URLs mostly according to how they are defined in RFC 3986, and has done so since the beginning. Web browsers mostly adhere to the WHATWG URL Specification. This deviance makes some URLs copied between browsers (or returned over HTTP for redirection) and curl not work the same way. It can also cause problems if an application parses URLs differently from libcurl and makes different assumptions about a link. This can mislead users into getting the wrong thing, connecting to the wrong host or otherwise not working identically. Within an application, this can be mitigated by always using the \fIcurl_url(3)\fP API to parse URLs, ensuring that they are parsed the same way as within libcurl itself. .SH FTP uses two connections When performing an FTP transfer, two TCP connections are used: one for setting up the transfer and one for the actual data. FTP is not only unauthenticated, but the setting up of the second transfer is also a weak spot. The second connection to use for data, is either setup with the PORT/EPRT command that makes the server connect back to the client on the given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen to and tells the client to connect to a given IP+PORT. Again, unauthenticated means that the connection might be meddled with by a man\-in\-the\-middle or that there is a malicious server pretending to be the right one. A malicious FTP server can respond to PASV commands with the IP+PORT of a totally different machine. Perhaps even a third party host, and when there are many clients trying to connect to that third party, it could create a Distributed Denial\-Of\-Service attack out of it. If the client makes an upload operation, it can make the client send the data to another site. If the attacker can affect what data the client uploads, it can be made to work as a HTTP request and then the client could be made to issue HTTP requests to third party hosts. An attacker that manages to control curl\(aqs command line options can tell curl to send an FTP PORT command to ask the server to connect to a third party host instead of back to curl. The fact that FTP uses two connections makes it vulnerable in a way that is hard to avoid. .SH Active FTP passes on the local IP address If you use curl/libcurl to do \fIactive\fP FTP transfers, curl passes on the address of your local IP to the remote server \- even when for example using a SOCKS or HTTP proxy in between curl and the target server. .SH Denial of Service A malicious server could cause libcurl to effectively hang by sending data slowly, or even no data at all but just keeping the TCP connection open. This could effectively result in a denial\-of\-service attack. The \fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can be used to mitigate against this. A malicious server could cause libcurl to download an infinite amount of data, potentially causing system resources to be exhausted resulting in a system or application crash. Setting the \fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against this. Instead, applications should monitor the amount of data received within the write or progress callback and abort once the limit is reached. A malicious HTTP server could cause an infinite redirection loop, causing a denial\-of\-service. This can be mitigated by using the \fICURLOPT_MAXREDIRS(3)\fP option. .SH Arbitrary Headers User\-supplied data must be sanitized when used in options like \fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP, \fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured data. Characters like embedded carriage returns or ampersands could allow the user to create additional headers or fields that could cause malicious transactions. .SH Server-supplied Names A server can supply data which the application may, in some cases, use as a filename. The curl command\-line tool does this with \fI\--remote\-header\-name\fP, using the Content\-disposition: header to generate a filename. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to generate a filename from a server\-supplied redirect URL. Special care must be taken to sanitize such names to avoid the possibility of a malicious server supplying one like \fB"/etc/passwd"\fP, \fB"autoexec.bat"\fP, \fB"prn:"\fP or even \fB".bashrc"\fP. .SH Server Certificates A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP option to disable certificate validation. There are numerous attacks that are enabled by applications that fail to properly validate server TLS/SSL certificates, thus enabling a malicious server to spoof a legitimate one. HTTPS without validated certificates is potentially as insecure as a plain HTTP connection. .SH Showing What You Do Relatedly, be aware that in situations when you have problems with libcurl and ask someone for help, everything you reveal in order to get best possible help might also impose certain security related risks. Hostnames, usernames, paths, operating system specifics, etc. (not to mention passwords of course) may in fact be used by intruders to gain additional information of a potential target. Be sure to limit access to application logs if they could hold private or security\-related data. Besides the obvious candidates like usernames and passwords, things like URLs, cookies or even filenames could also hold sensitive data. To avoid this problem, you must of course use your common sense. Often, you can just edit out the sensitive data or just search/replace your true information with faked data. .SH setuid applications using libcurl libcurl\-using applications that set the \(aqsetuid\(aq bit to run with elevated or modified rights also implicitly give that extra power to libcurl and this should only be done after careful considerations. Giving setuid powers to the application means that libcurl can save files using those new rights (if for example the \fISSLKEYLOGFILE\fP environment variable is set). Also: if the application wants these powers to read or manage secrets that the user is otherwise not able to view (like credentials for a login etc), it should be noted that libcurl still might understand proxy environment variables that allow the user to redirect libcurl operations to use a proxy controlled by the user. .SH File descriptors, fork and NTLM An application that uses libcurl and invokes \fIfork()\fP gets all file descriptors duplicated in the child process, including the ones libcurl created. libcurl itself uses \fIfork()\fP and \fIexecl()\fP if told to use the \fBCURLAUTH_NTLM_WB\fP authentication method which then invokes the helper command in a child process with file descriptors duplicated. Make sure that only the trusted and reliable helper program is invoked. This feature was removed from curl in 8.8.0. .SH Secrets in memory When applications pass usernames, passwords or other sensitive data to libcurl to be used for upcoming transfers, those secrets are kept around as\-is in memory. In many cases they are stored in the heap for as long as the handle itself for which the options are set. If an attacker can access the heap, like maybe by reading swap space or via a core dump file, such data might be accessible. Further, when eventually closing a handle and the secrets are no longer needed, libcurl does not explicitly clear memory before freeing it, so credentials may be left in freed data. .SH Saving files libcurl cannot protect against attacks where an attacker has write access to the same directory where libcurl is directed to save files. .SH Cookies If libcurl is built with PSL (\fBPublic Suffix List\fP) support, it detects and discards cookies that are specified for such suffix domains that should not be allowed to have cookies. if libcurl is \fInot\fP built with PSL support, it has no ability to stop super cookies. .SH Report Security Problems Should you detect or just suspect a security problem in libcurl or curl, contact the project curl security team immediately. See https://curl.se/dev/secprocess.html for details. .SH SEE ALSO .BR libcurl-thread (3)	22.17 KB	2025-07-08 09:41
📄 libcurl-share.3 .\" generated by cd2nroff 0.1 from libcurl-share.md .TH libcurl-share 3 "2025-06-27" libcurl .SH NAME libcurl\-share \- how to use the share interface .SH DESCRIPTION This is an overview on how to use the libcurl share interface in your C programs. There are specific man pages for each function mentioned in here. All functions in the share interface are prefixed with curl_share. .SH OBJECTIVES The share interface was added to enable sharing of data between curl handles. .SH ONE SET OF DATA - MANY TRANSFERS You can have multiple easy handles share data between them. Have them update and use the \fBsame\fP cookie database, DNS cache, TLS session cache and/or connection cache. This way, each single transfer takes advantage from data updates made by the other transfer(s). .SH SHARE OBJECT You create a shared object with \fIcurl_share_init(3)\fP. It returns a handle for a newly created one. You tell the shared object what data you want it to share by using \fIcurl_share_setopt(3)\fP. Since you can use this share from multiple threads, and libcurl has no internal thread synchronization, you must provide mutex callbacks if you are using this multi\-threaded. You set lock and unlock functions with \fIcurl_share_setopt(3)\fP too. Then, you make an easy handle to use this share, you set the \fICURLOPT_SHARE(3)\fP option with \fIcurl_easy_setopt(3)\fP, and pass in share handle. You can make any number of easy handles share the same share handle. To make an easy handle stop using that particular share, you set \fICURLOPT_SHARE(3)\fP to NULL for that easy handle. To make a handle stop sharing a particular data, you can \fICURLSHOPT_UNSHARE(3)\fP it. When you are done using the share, make sure that no easy handle is still using it, and call \fIcurl_share_cleanup(3)\fP on the handle. .SH SEE ALSO .BR curl_share_cleanup (3), .BR curl_share_init (3), .BR curl_share_setopt (3), .BR libcurl-easy (3), .BR libcurl-errors (3), .BR libcurl-multi (3)	1.92 KB	2025-07-08 09:41
📄 libcurl-symbols.3 .\" generated by cd2nroff 0.1 from libcurl-symbols.md .TH libcurl-symbols 3 "2025-06-27" libcurl .SH libcurl symbols This man page details version information for public symbols provided in the libcurl header files. This lists the first version in which the symbol was introduced and for some symbols two additional information pieces: The first version in which the symbol is marked "deprecated" \- meaning that since that version no new code should be written to use the symbol as it is marked for getting removed in a future. The last version that featured the specific symbol. Using the symbol in source code makes it no longer compile error\-free after that specified version. This man page is automatically generated from the symbols\-in\-versions file. .IP CURL_AT_LEAST_VERSION Introduced in 7.43.0. .IP CURL_BLOB_COPY Introduced in 7.71.0. .IP CURL_BLOB_NOCOPY Introduced in 7.71.0. .IP CURL_CHUNK_BGN_FUNC_FAIL Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURL_CHUNK_BGN_FUNC_OK Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURL_CHUNK_BGN_FUNC_SKIP Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURL_CHUNK_END_FUNC_FAIL Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. .IP CURL_CHUNK_END_FUNC_OK Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. .IP CURL_CSELECT_ERR Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. .IP CURL_CSELECT_IN Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. .IP CURL_CSELECT_OUT Introduced in 7.16.3. See \fIcurl_multi_socket_action(3)\fP. .IP CURL_DEPRECATED Introduced in 7.87.0. .IP CURL_DID_MEMORY_FUNC_TYPEDEFS Introduced in 7.49.0. .IP CURL_EASY_NONE Introduced in 7.14.0. Last used in 7.15.4. .IP CURL_EASY_TIMEOUT Introduced in 7.14.0. Last used in 7.15.4. .IP CURL_ERROR_SIZE Introduced in 7.1. .IP CURL_FNMATCHFUNC_FAIL Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .IP CURL_FNMATCHFUNC_MATCH Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .IP CURL_FNMATCHFUNC_NOMATCH Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .IP CURL_FORMADD_DISABLED Introduced in 7.12.1. Deprecated since 7.56.0. .IP CURL_FORMADD_ILLEGAL_ARRAY Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_INCOMPLETE Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_MEMORY Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_NULL Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_OK Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_OPTION_TWICE Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_FORMADD_UNKNOWN_OPTION Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURL_GLOBAL_ACK_EINTR Introduced in 7.30.0. See \fIcurl_global_init(3)\fP. .IP CURL_GLOBAL_ALL Introduced in 7.8. See \fIcurl_global_init(3)\fP. .IP CURL_GLOBAL_DEFAULT Introduced in 7.8. See \fIcurl_global_init(3)\fP. .IP CURL_GLOBAL_NOTHING Introduced in 7.8. See \fIcurl_global_init(3)\fP. .IP CURL_GLOBAL_SSL Introduced in 7.8. See \fIcurl_global_init(3)\fP. .IP CURL_GLOBAL_WIN32 Introduced in 7.8.1. See \fIcurl_global_init(3)\fP. .IP CURL_HAS_DECLSPEC_ATTRIBUTE Introduced in 8.13.0. .IP CURL_HET_DEFAULT Introduced in 7.59.0. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP. .IP CURL_HTTP_VERSION_1_0 Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_1_1 Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_2 Introduced in 7.43.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_2_0 Introduced in 7.33.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_2_PRIOR_KNOWLEDGE Introduced in 7.49.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_2TLS Introduced in 7.47.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_3 Introduced in 7.66.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_3ONLY Introduced in 7.88.0. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTP_VERSION_NONE Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURL_HTTPPOST_BUFFER Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_CALLBACK Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_FILENAME Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_LARGE Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_PTRBUFFER Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_PTRCONTENTS Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_PTRNAME Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_HTTPPOST_READFILE Introduced in 7.46.0. See \fIcurl_formadd(3)\fP. .IP CURL_IGNORE_DEPRECATION Introduced in 7.87.0. .IP CURL_IPRESOLVE_V4 Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. .IP CURL_IPRESOLVE_V6 Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. .IP CURL_IPRESOLVE_WHATEVER Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. .IP CURL_ISOCPP Introduced in 7.10.2. .IP CURL_LOCK_ACCESS_NONE Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_ACCESS_SHARED Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_ACCESS_SINGLE Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_CONNECT Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_COOKIE Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_DNS Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_HSTS Introduced in 7.88.0. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_NONE Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_PSL Introduced in 7.61.0. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_SHARE Introduced in 7.10.4. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_DATA_SSL_SESSION Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURL_LOCK_TYPE_CONNECT Introduced in 7.10. Last used in 7.10.2. .IP CURL_LOCK_TYPE_COOKIE Introduced in 7.10. Last used in 7.10.2. .IP CURL_LOCK_TYPE_DNS Introduced in 7.10. Last used in 7.10.2. .IP CURL_LOCK_TYPE_NONE Introduced in 7.10. Last used in 7.10.2. .IP CURL_LOCK_TYPE_SSL_SESSION Introduced in 7.10. Last used in 7.10.2. .IP CURL_MAX_HTTP_HEADER Introduced in 7.19.7. .IP CURL_MAX_READ_SIZE Introduced in 7.53.0. .IP CURL_MAX_WRITE_SIZE Introduced in 7.9.7. .IP CURL_NETRC_IGNORED Introduced in 7.9.8. .IP CURL_NETRC_OPTIONAL Introduced in 7.9.8. .IP CURL_NETRC_REQUIRED Introduced in 7.9.8. .IP CURL_POLL_IN Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURL_POLL_INOUT Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURL_POLL_NONE Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURL_POLL_OUT Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURL_POLL_REMOVE Introduced in 7.14.0. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURL_PREREQFUNC_ABORT Introduced in 7.79.0. .IP CURL_PREREQFUNC_OK Introduced in 7.79.0. .IP CURL_PROGRESS_BAR Introduced in 7.1.1. Last used in 7.4.1. .IP CURL_PROGRESS_STATS Introduced in 7.1.1. Last used in 7.4.1. .IP CURL_PROGRESSFUNC_CONTINUE Introduced in 7.68.0. .IP CURL_PULL_SYS_POLL_H Introduced in 7.56.0. .IP CURL_PUSH_DENY Introduced in 7.44.0. .IP CURL_PUSH_ERROROUT Introduced in 7.72.0. .IP CURL_PUSH_OK Introduced in 7.44.0. .IP CURL_READFUNC_ABORT Introduced in 7.12.1. .IP CURL_READFUNC_PAUSE Introduced in 7.18.0. .IP CURL_REDIR_GET_ALL Introduced in 7.19.1. .IP CURL_REDIR_POST_301 Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. .IP CURL_REDIR_POST_302 Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. .IP CURL_REDIR_POST_303 Introduced in 7.26.0. See \fICURLOPT_POSTREDIR(3)\fP. .IP CURL_REDIR_POST_ALL Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. .IP CURL_RTSPREQ_ANNOUNCE Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_DESCRIBE Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_GET_PARAMETER Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_NONE Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_OPTIONS Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_PAUSE Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_PLAY Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_RECEIVE Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_RECORD Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_SET_PARAMETER Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_SETUP Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_RTSPREQ_TEARDOWN Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURL_SEEKFUNC_CANTSEEK Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. .IP CURL_SEEKFUNC_FAIL Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. .IP CURL_SEEKFUNC_OK Introduced in 7.19.5. See \fICURLOPT_SEEKFUNCTION(3)\fP. .IP CURL_SOCKET_BAD Introduced in 7.14.0. .IP CURL_SOCKET_TIMEOUT Introduced in 7.14.0. .IP CURL_SOCKOPT_ALREADY_CONNECTED Introduced in 7.21.5. .IP CURL_SOCKOPT_ERROR Introduced in 7.21.5. .IP CURL_SOCKOPT_OK Introduced in 7.21.5. .IP CURL_SSLVERSION_DEFAULT Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_DEFAULT Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_NONE Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_TLSv1_0 Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_TLSv1_1 Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_TLSv1_2 Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_MAX_TLSv1_3 Introduced in 7.54.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_SSLv2 Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_SSLv3 Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_TLSv1 Introduced in 7.9.2. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_TLSv1_0 Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_TLSv1_1 Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_TLSv1_2 Introduced in 7.34.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_SSLVERSION_TLSv1_3 Introduced in 7.52.0. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURL_STRICTER Introduced in 7.50.2. .IP CURL_TIMECOND_IFMODSINCE Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. .IP CURL_TIMECOND_IFUNMODSINCE Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. .IP CURL_TIMECOND_LASTMOD Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. .IP CURL_TIMECOND_NONE Introduced in 7.9.7. See \fICURLOPT_TIMECONDITION(3)\fP. .IP CURL_TLSAUTH_NONE Introduced in 7.21.4. .IP CURL_TLSAUTH_SRP Introduced in 7.21.4. .IP CURL_TRAILERFUNC_ABORT Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. .IP CURL_TRAILERFUNC_OK Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. .IP CURL_UPKEEP_INTERVAL_DEFAULT Introduced in 7.62.0. .IP CURL_VERSION_ALTSVC Introduced in 7.64.1. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_ASYNCHDNS Introduced in 7.10.7. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_BITS Introduced in 7.43.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_BROTLI Introduced in 7.57.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_CONV Introduced in 7.15.4. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_CURLDEBUG Introduced in 7.19.6. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_DEBUG Introduced in 7.10.6. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_GSASL Introduced in 7.76.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_GSSAPI Introduced in 7.38.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_GSSNEGOTIATE Introduced in 7.10.6. Deprecated since 7.38.0. .IP CURL_VERSION_HSTS Introduced in 7.74.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_HTTP2 Introduced in 7.33.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_HTTP3 Introduced in 7.66.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_HTTPS_PROXY Introduced in 7.52.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_IDN Introduced in 7.12.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_IPV6 Introduced in 7.10. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_KERBEROS4 Introduced in 7.10. Deprecated since 7.33.0. .IP CURL_VERSION_KERBEROS5 Introduced in 7.40.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_LARGEFILE Introduced in 7.11.1. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_LIBZ Introduced in 7.10. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_MULTI_SSL Introduced in 7.56.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_NTLM Introduced in 7.10.6. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_NTLM_WB Introduced in 7.22.0. Deprecated since 8.8.0. .IP CURL_VERSION_PSL Introduced in 7.47.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_SPNEGO Introduced in 7.10.8. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_SSL Introduced in 7.10. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_SSPI Introduced in 7.13.2. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_THREADSAFE Introduced in 7.84.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_TLSAUTH_SRP Introduced in 7.21.4. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_UNICODE Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_UNIX_SOCKETS Introduced in 7.40.0. See \fIcurl_version_info(3)\fP. .IP CURL_VERSION_ZSTD Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. .IP CURL_WAIT_POLLIN Introduced in 7.28.0. .IP CURL_WAIT_POLLOUT Introduced in 7.28.0. .IP CURL_WAIT_POLLPRI Introduced in 7.28.0. .IP CURL_WIN32 Introduced in 7.69.0. Last used in 8.5.0. .IP CURL_WRITEFUNC_ERROR Introduced in 7.87.0. .IP CURL_WRITEFUNC_PAUSE Introduced in 7.18.0. .IP CURL_ZERO_TERMINATED Introduced in 7.56.0. .IP CURLALTSVC_H1 Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. .IP CURLALTSVC_H2 Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. .IP CURLALTSVC_H3 Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. .IP CURLALTSVC_READONLYFILE Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. .IP CURLAUTH_ANY Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_ANYSAFE Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_AWS_SIGV4 Introduced in 7.75.0. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_BASIC Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_BEARER Introduced in 7.61.0. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_DIGEST Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_DIGEST_IE Introduced in 7.19.3. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_GSSAPI Introduced in 7.55.0. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_GSSNEGOTIATE Introduced in 7.10.6. Deprecated since 7.38.0. .IP CURLAUTH_NEGOTIATE Introduced in 7.38.0. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_NONE Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_NTLM Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLAUTH_NTLM_WB Introduced in 7.22.0. Deprecated since 8.8.0. .IP CURLAUTH_ONLY Introduced in 7.21.3. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLCLOSEPOLICY_CALLBACK Introduced in 7.7. Deprecated since 7.16.1. .IP CURLCLOSEPOLICY_LEAST_RECENTLY_USED Introduced in 7.7. Deprecated since 7.16.1. .IP CURLCLOSEPOLICY_LEAST_TRAFFIC Introduced in 7.7. Deprecated since 7.16.1. .IP CURLCLOSEPOLICY_NONE Introduced in 7.7. Deprecated since 7.16.1. .IP CURLCLOSEPOLICY_OLDEST Introduced in 7.7. Deprecated since 7.16.1. .IP CURLCLOSEPOLICY_SLOWEST Introduced in 7.7. Deprecated since 7.16.1. .IP CURLE_ABORTED_BY_CALLBACK Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_AGAIN Introduced in 7.18.2. See \fIlibcurl\-errors(3)\fP. .IP CURLE_ALREADY_COMPLETE Introduced in 7.7.2. Deprecated since 7.8. .IP CURLE_AUTH_ERROR Introduced in 7.66.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_BAD_CALLING_ORDER Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_BAD_CONTENT_ENCODING Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_BAD_DOWNLOAD_RESUME Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_BAD_FUNCTION_ARGUMENT Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_BAD_PASSWORD_ENTERED Introduced in 7.4.2. Deprecated since 7.17.0. .IP CURLE_CHUNK_FAILED Introduced in 7.21.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_CONV_FAILED Introduced in 7.15.4. Deprecated since 7.82.0. .IP CURLE_CONV_REQD Introduced in 7.15.4. Deprecated since 7.82.0. .IP CURLE_COULDNT_CONNECT Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_COULDNT_RESOLVE_HOST Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_COULDNT_RESOLVE_PROXY Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FAILED_INIT Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FILE_COULDNT_READ_FILE Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FILESIZE_EXCEEDED Introduced in 7.10.8. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_ACCEPT_FAILED Introduced in 7.24.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_ACCEPT_TIMEOUT Introduced in 7.24.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_ACCESS_DENIED Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_BAD_DOWNLOAD_RESUME Introduced in 7.1. Deprecated since 7.1. .IP CURLE_FTP_BAD_FILE_LIST Introduced in 7.21.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_CANT_GET_HOST Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_CANT_RECONNECT Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_COULDNT_GET_SIZE Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_COULDNT_RETR_FILE Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_COULDNT_SET_ASCII Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_COULDNT_SET_BINARY Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_COULDNT_SET_TYPE Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_COULDNT_STOR_FILE Introduced in 7.1. Deprecated since 7.16.3. .IP CURLE_FTP_COULDNT_USE_REST Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_PARTIAL_FILE Introduced in 7.1. Deprecated since 7.1. .IP CURLE_FTP_PORT_FAILED Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_PRET_FAILED Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_QUOTE_ERROR Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_SSL_FAILED Introduced in 7.11.0. Deprecated since 7.17.0. .IP CURLE_FTP_USER_PASSWORD_INCORRECT Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_WEIRD_227_FORMAT Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_WEIRD_PASS_REPLY Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_WEIRD_PASV_REPLY Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_FTP_WEIRD_SERVER_REPLY Introduced in 7.1. Deprecated since 7.51.0. .IP CURLE_FTP_WEIRD_USER_REPLY Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FTP_WRITE_ERROR Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_FUNCTION_NOT_FOUND Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_GOT_NOTHING Introduced in 7.9.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_HTTP2 Introduced in 7.38.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_HTTP2_STREAM Introduced in 7.49.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_HTTP3 Introduced in 7.68.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_HTTP_NOT_FOUND Introduced in 7.1. Deprecated since 7.10.3. .IP CURLE_HTTP_PORT_FAILED Introduced in 7.3. Deprecated since 7.12.0. .IP CURLE_HTTP_POST_ERROR Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_HTTP_RANGE_ERROR Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_HTTP_RETURNED_ERROR Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_INTERFACE_FAILED Introduced in 7.12.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_LDAP_CANNOT_BIND Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_LDAP_INVALID_URL Introduced in 7.10.8. Deprecated since 7.82.0. .IP CURLE_LDAP_SEARCH_FAILED Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_LIBRARY_NOT_FOUND Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_LOGIN_DENIED Introduced in 7.13.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_MALFORMAT_USER Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_NO_CONNECTION_AVAILABLE Introduced in 7.30.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_NOT_BUILT_IN Introduced in 7.21.5. See \fIlibcurl\-errors(3)\fP. .IP CURLE_OK Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_OPERATION_TIMEDOUT Introduced in 7.10.2. See \fIlibcurl\-errors(3)\fP. .IP CURLE_OPERATION_TIMEOUTED Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_OUT_OF_MEMORY Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_PARTIAL_FILE Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_PEER_FAILED_VERIFICATION Introduced in 7.17.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_PROXY Introduced in 7.73.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_QUIC_CONNECT_ERROR Introduced in 7.69.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_QUOTE_ERROR Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_RANGE_ERROR Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_READ_ERROR Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_RECURSIVE_API_CALL Introduced in 7.59.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_RECV_ERROR Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_REMOTE_ACCESS_DENIED Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_REMOTE_DISK_FULL Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_REMOTE_FILE_EXISTS Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_REMOTE_FILE_NOT_FOUND Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_RTSP_CSEQ_ERROR Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_RTSP_SESSION_ERROR Introduced in 7.20.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SEND_ERROR Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SEND_FAIL_REWIND Introduced in 7.12.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SETOPT_OPTION_SYNTAX Introduced in 7.78.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SHARE_IN_USE Introduced in 7.9.6. Deprecated since 7.17.0. .IP CURLE_SSH Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CACERT Introduced in 7.10. Deprecated since 7.62.0. .IP CURLE_SSL_CACERT_BADFILE Introduced in 7.16.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CERTPROBLEM Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CIPHER Introduced in 7.10. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CLIENTCERT Introduced in 7.77.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CONNECT_ERROR Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_CRL_BADFILE Introduced in 7.19.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_ENGINE_INITFAILED Introduced in 7.12.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_ENGINE_NOTFOUND Introduced in 7.9.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_ENGINE_SETFAILED Introduced in 7.9.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_INVALIDCERTSTATUS Introduced in 7.41.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_ISSUER_ERROR Introduced in 7.19.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_PEER_CERTIFICATE Introduced in 7.8. Deprecated since 7.17.1. .IP CURLE_SSL_PINNEDPUBKEYNOTMATCH Introduced in 7.39.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_SSL_SHUTDOWN_FAILED Introduced in 7.16.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TELNET_OPTION_SYNTAX Introduced in 7.7. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TFTP_DISKFULL Introduced in 7.15.0. Deprecated since 7.17.0. .IP CURLE_TFTP_EXISTS Introduced in 7.15.0. Deprecated since 7.17.0. .IP CURLE_TFTP_ILLEGAL Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TFTP_NOSUCHUSER Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TFTP_NOTFOUND Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TFTP_PERM Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TFTP_UNKNOWNID Introduced in 7.15.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TOO_LARGE Introduced in 8.6.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_TOO_MANY_REDIRECTS Introduced in 7.5. See \fIlibcurl\-errors(3)\fP. .IP CURLE_UNKNOWN_OPTION Introduced in 7.21.5. See \fIlibcurl\-errors(3)\fP. .IP CURLE_UNKNOWN_TELNET_OPTION Introduced in 7.7. Deprecated since 7.21.5. .IP CURLE_UNRECOVERABLE_POLL Introduced in 7.84.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_UNSUPPORTED_PROTOCOL Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_UPLOAD_FAILED Introduced in 7.16.3. See \fIlibcurl\-errors(3)\fP. .IP CURLE_URL_MALFORMAT Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLE_ECH_REQUIRED Introduced in 8.8.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_URL_MALFORMAT_USER Introduced in 7.1. Deprecated since 7.17.0. .IP CURLE_USE_SSL_FAILED Introduced in 7.17.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_WEIRD_SERVER_REPLY Introduced in 7.51.0. See \fIlibcurl\-errors(3)\fP. .IP CURLE_WRITE_ERROR Introduced in 7.1. See \fIlibcurl\-errors(3)\fP. .IP CURLFILETYPE_DEVICE_BLOCK Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_DEVICE_CHAR Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_DIRECTORY Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_DOOR Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_FILE Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_NAMEDPIPE Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_SOCKET Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_SYMLINK Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFILETYPE_UNKNOWN Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_FILENAME Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_FILETYPE Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_GID Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_HLINKCOUNT Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_PERM Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_SIZE Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_TIME Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFINFOFLAG_KNOWN_UID Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLFOLLOW_ALL Introduced in 8.13.0. .IP CURLFOLLOW_OBEYCODE Introduced in 8.13.0. .IP CURLFOLLOW_FIRSTONLY Introduced in 8.13.0. .IP CURLFORM_ARRAY Introduced in 7.9.1. Deprecated since 7.56.0. .IP CURLFORM_ARRAY_END Introduced in 7.9.1. Deprecated since 7.9.5. .IP CURLFORM_ARRAY_START Introduced in 7.9.1. Deprecated since 7.9.5. .IP CURLFORM_BUFFER Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURLFORM_BUFFERLENGTH Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURLFORM_BUFFERPTR Introduced in 7.9.8. Deprecated since 7.56.0. .IP CURLFORM_CONTENTHEADER Introduced in 7.9.3. Deprecated since 7.56.0. .IP CURLFORM_CONTENTLEN Introduced in 7.46.0. Deprecated since 7.56.0. .IP CURLFORM_CONTENTSLENGTH Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_CONTENTTYPE Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_COPYCONTENTS Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_COPYNAME Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_END Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_FILE Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_FILECONTENT Introduced in 7.9.1. Deprecated since 7.56.0. .IP CURLFORM_FILENAME Introduced in 7.9.6. Deprecated since 7.56.0. .IP CURLFORM_NAMELENGTH Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_NOTHING Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_PTRCONTENTS Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_PTRNAME Introduced in 7.9. Deprecated since 7.56.0. .IP CURLFORM_STREAM Introduced in 7.18.2. Deprecated since 7.56.0. .IP CURLFTP_CREATE_DIR Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. .IP CURLFTP_CREATE_DIR_NONE Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. .IP CURLFTP_CREATE_DIR_RETRY Introduced in 7.19.4. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. .IP CURLFTPAUTH_DEFAULT Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. .IP CURLFTPAUTH_SSL Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. .IP CURLFTPAUTH_TLS Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. .IP CURLFTPMETHOD_DEFAULT Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. .IP CURLFTPMETHOD_MULTICWD Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. .IP CURLFTPMETHOD_NOCWD Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. .IP CURLFTPMETHOD_SINGLECWD Introduced in 7.15.3. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. .IP CURLFTPSSL_ALL Introduced in 7.11.0. Deprecated since 7.17.0. .IP CURLFTPSSL_CCC_ACTIVE Introduced in 7.16.2. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLFTPSSL_CCC_NONE Introduced in 7.16.2. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLFTPSSL_CCC_PASSIVE Introduced in 7.16.1. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLFTPSSL_CONTROL Introduced in 7.11.0. Deprecated since 7.17.0. .IP CURLFTPSSL_NONE Introduced in 7.11.0. Deprecated since 7.17.0. .IP CURLFTPSSL_TRY Introduced in 7.11.0. Deprecated since 7.17.0. .IP CURLGSSAPI_DELEGATION_FLAG Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. .IP CURLGSSAPI_DELEGATION_NONE Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. .IP CURLGSSAPI_DELEGATION_POLICY_FLAG Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. .IP CURLH_1XX Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. .IP CURLH_CONNECT Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. .IP CURLH_HEADER Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. .IP CURLH_PSEUDO Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. .IP CURLH_TRAILER Introduced in 7.83.0. See \fIcurl_easy_header(3)\fP. .IP CURLHE_BAD_ARGUMENT Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_BADINDEX Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_MISSING Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_NOHEADERS Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_NOREQUEST Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_NOT_BUILT_IN Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_OK Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHE_OUT_OF_MEMORY Introduced in 7.83.0. See \fIlibcurl\-errors(3)\fP. .IP CURLHEADER_SEPARATE Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. .IP CURLHEADER_UNIFIED Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. .IP CURLHSTS_ENABLE Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. .IP CURLHSTS_READONLYFILE Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. .IP CURLINFO_ACTIVESOCKET Introduced in 7.45.0. .IP CURLINFO_APPCONNECT_TIME Introduced in 7.19.0. .IP CURLINFO_APPCONNECT_TIME_T Introduced in 7.61.0. .IP CURLINFO_CAINFO Introduced in 7.84.0. .IP CURLINFO_CAPATH Introduced in 7.84.0. .IP CURLINFO_CERTINFO Introduced in 7.19.1. .IP CURLINFO_CONDITION_UNMET Introduced in 7.19.4. .IP CURLINFO_CONN_ID Introduced in 8.2.0. .IP CURLINFO_CONNECT_TIME Introduced in 7.4.1. .IP CURLINFO_CONNECT_TIME_T Introduced in 7.61.0. .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD Introduced in 7.6.1. Deprecated since 7.55.0. .IP CURLINFO_CONTENT_LENGTH_DOWNLOAD_T Introduced in 7.55.0. .IP CURLINFO_CONTENT_LENGTH_UPLOAD Introduced in 7.6.1. Deprecated since 7.55.0. .IP CURLINFO_CONTENT_LENGTH_UPLOAD_T Introduced in 7.55.0. .IP CURLINFO_CONTENT_TYPE Introduced in 7.9.4. .IP CURLINFO_COOKIELIST Introduced in 7.14.1. .IP CURLINFO_DATA_IN Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_DATA_OUT Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_DOUBLE Introduced in 7.4.1. .IP CURLINFO_EARLYDATA_SENT_T Introduced in 8.11.0. .IP CURLINFO_EFFECTIVE_METHOD Introduced in 7.72.0. .IP CURLINFO_EFFECTIVE_URL Introduced in 7.4. .IP CURLINFO_END Introduced in 7.9.6. .IP CURLINFO_FILETIME Introduced in 7.5. .IP CURLINFO_FILETIME_T Introduced in 7.59.0. .IP CURLINFO_FTP_ENTRY_PATH Introduced in 7.15.4. .IP CURLINFO_HEADER_IN Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_HEADER_OUT Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_HEADER_SIZE Introduced in 7.4.1. .IP CURLINFO_HTTP_CODE Introduced in 7.4.1. Deprecated since 7.10.8. .IP CURLINFO_HTTP_CONNECTCODE Introduced in 7.10.7. .IP CURLINFO_HTTP_VERSION Introduced in 7.50.0. .IP CURLINFO_HTTPAUTH_AVAIL Introduced in 7.10.8. .IP CURLINFO_HTTPAUTH_USED Introduced in 8.12.0. .IP CURLINFO_LASTONE Introduced in 7.4.1. .IP CURLINFO_LASTSOCKET Introduced in 7.15.2. Deprecated since 7.45.0. .IP CURLINFO_LOCAL_IP Introduced in 7.21.0. .IP CURLINFO_LOCAL_PORT Introduced in 7.21.0. .IP CURLINFO_LONG Introduced in 7.4.1. .IP CURLINFO_MASK Introduced in 7.4.1. .IP CURLINFO_NAMELOOKUP_TIME Introduced in 7.4.1. .IP CURLINFO_NAMELOOKUP_TIME_T Introduced in 7.61.0. .IP CURLINFO_NONE Introduced in 7.4.1. .IP CURLINFO_NUM_CONNECTS Introduced in 7.12.3. .IP CURLINFO_OFF_T Introduced in 7.55.0. .IP CURLINFO_OS_ERRNO Introduced in 7.12.2. .IP CURLINFO_PRETRANSFER_TIME Introduced in 7.4.1. .IP CURLINFO_PRETRANSFER_TIME_T Introduced in 7.61.0. .IP CURLINFO_POSTTRANSFER_TIME_T Introduced in 8.10.0. .IP CURLINFO_PRIMARY_IP Introduced in 7.19.0. .IP CURLINFO_PRIMARY_PORT Introduced in 7.21.0. .IP CURLINFO_PRIVATE Introduced in 7.10.3. .IP CURLINFO_PROTOCOL Introduced in 7.52.0. Deprecated since 7.85.0. .IP CURLINFO_PROXY_ERROR Introduced in 7.73.0. .IP CURLINFO_PROXY_SSL_VERIFYRESULT Introduced in 7.52.0. .IP CURLINFO_PROXYAUTH_AVAIL Introduced in 7.10.8. .IP CURLINFO_PROXYAUTH_USED Introduced in 8.12.0. .IP CURLINFO_PTR Introduced in 7.54.1. .IP CURLINFO_QUEUE_TIME_T Introduced in 8.6.0. .IP CURLINFO_REDIRECT_COUNT Introduced in 7.9.7. .IP CURLINFO_REDIRECT_TIME Introduced in 7.9.7. .IP CURLINFO_REDIRECT_TIME_T Introduced in 7.61.0. .IP CURLINFO_REDIRECT_URL Introduced in 7.18.2. .IP CURLINFO_REFERER Introduced in 7.76.0. .IP CURLINFO_REQUEST_SIZE Introduced in 7.4.1. .IP CURLINFO_RESPONSE_CODE Introduced in 7.10.8. .IP CURLINFO_RETRY_AFTER Introduced in 7.66.0. .IP CURLINFO_RTSP_CLIENT_CSEQ Introduced in 7.20.0. .IP CURLINFO_RTSP_CSEQ_RECV Introduced in 7.20.0. .IP CURLINFO_RTSP_SERVER_CSEQ Introduced in 7.20.0. .IP CURLINFO_RTSP_SESSION_ID Introduced in 7.20.0. .IP CURLINFO_SCHEME Introduced in 7.52.0. .IP CURLINFO_SIZE_DOWNLOAD Introduced in 7.4.1. Deprecated since 7.55.0. .IP CURLINFO_SIZE_DOWNLOAD_T Introduced in 7.55.0. .IP CURLINFO_SIZE_UPLOAD Introduced in 7.4.1. Deprecated since 7.55.0. .IP CURLINFO_SIZE_UPLOAD_T Introduced in 7.55.0. .IP CURLINFO_SLIST Introduced in 7.12.3. .IP CURLINFO_SOCKET Introduced in 7.45.0. .IP CURLINFO_SPEED_DOWNLOAD Introduced in 7.4.1. Deprecated since 7.55.0. .IP CURLINFO_SPEED_DOWNLOAD_T Introduced in 7.55.0. .IP CURLINFO_SPEED_UPLOAD Introduced in 7.4.1. Deprecated since 7.55.0. .IP CURLINFO_SPEED_UPLOAD_T Introduced in 7.55.0. .IP CURLINFO_SSL_DATA_IN Introduced in 7.12.1. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_SSL_DATA_OUT Introduced in 7.12.1. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_SSL_ENGINES Introduced in 7.12.3. .IP CURLINFO_SSL_VERIFYRESULT Introduced in 7.5. .IP CURLINFO_STARTTRANSFER_TIME Introduced in 7.9.2. .IP CURLINFO_STARTTRANSFER_TIME_T Introduced in 7.61.0. .IP CURLINFO_STRING Introduced in 7.4.1. .IP CURLINFO_TEXT Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLINFO_TLS_SESSION Introduced in 7.34.0. Deprecated since 7.48.0. .IP CURLINFO_TLS_SSL_PTR Introduced in 7.48.0. .IP CURLINFO_TOTAL_TIME Introduced in 7.4.1. .IP CURLINFO_TOTAL_TIME_T Introduced in 7.61.0. .IP CURLINFO_TYPEMASK Introduced in 7.4.1. .IP CURLINFO_USED_PROXY Introduced in 8.7.0. .IP CURLINFO_XFER_ID Introduced in 8.2.0. .IP CURLIOCMD_NOP Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. .IP CURLIOCMD_RESTARTREAD Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. .IP CURLIOE_FAILRESTART Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. .IP CURLIOE_OK Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. .IP CURLIOE_UNKNOWNCMD Introduced in 7.12.3. See \fICURLOPT_IOCTLFUNCTION(3)\fP. .IP CURLKHMATCH_MISMATCH Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHMATCH_MISSING Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHMATCH_OK Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHSTAT_DEFER Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHSTAT_FINE Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHSTAT_FINE_ADD_TO_FILE Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHSTAT_FINE_REPLACE Introduced in 7.73.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHSTAT_REJECT Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_DSS Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_ECDSA Introduced in 7.58.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_ED25519 Introduced in 7.58.0. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_RSA Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_RSA1 Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLKHTYPE_UNKNOWN Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLM_ABORTED_BY_CALLBACK Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLM_ADDED_ALREADY Introduced in 7.33.0. See \fIlibcurl\-errors(3)\fP. .IP CURLM_BAD_EASY_HANDLE Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_BAD_FUNCTION_ARGUMENT Introduced in 7.69.0. See \fIlibcurl\-errors(3)\fP. .IP CURLM_BAD_HANDLE Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_BAD_SOCKET Introduced in 7.15.4. See \fIlibcurl\-errors(3)\fP. .IP CURLM_CALL_MULTI_PERFORM Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_CALL_MULTI_SOCKET Introduced in 7.15.5. See \fIlibcurl\-errors(3)\fP. .IP CURLM_INTERNAL_ERROR Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_OK Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_OUT_OF_MEMORY Introduced in 7.9.6. See \fIlibcurl\-errors(3)\fP. .IP CURLM_RECURSIVE_API_CALL Introduced in 7.59.0. See \fIlibcurl\-errors(3)\fP. .IP CURLM_UNKNOWN_OPTION Introduced in 7.15.4. See \fIlibcurl\-errors(3)\fP. .IP CURLM_UNRECOVERABLE_POLL Introduced in 7.84.0. See \fIlibcurl\-errors(3)\fP. .IP CURLM_WAKEUP_FAILURE Introduced in 7.68.0. See \fIlibcurl\-errors(3)\fP. .IP CURLMIMEOPT_FORMESCAPE Introduced in 7.81.0. See \fICURLOPT_MIME_OPTIONS(3)\fP. .IP CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE Introduced in 7.30.0. See \fICURLMOPT_CHUNK_LENGTH_PENALTY_SIZE(3)\fP. .IP CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE Introduced in 7.30.0. See \fICURLMOPT_CONTENT_LENGTH_PENALTY_SIZE(3)\fP. .IP CURLMOPT_MAX_CONCURRENT_STREAMS Introduced in 7.67.0. See \fICURLMOPT_MAX_CONCURRENT_STREAMS(3)\fP. .IP CURLMOPT_MAX_HOST_CONNECTIONS Introduced in 7.30.0. See \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP. .IP CURLMOPT_MAX_PIPELINE_LENGTH Introduced in 7.30.0. See \fICURLMOPT_MAX_PIPELINE_LENGTH(3)\fP. .IP CURLMOPT_MAX_TOTAL_CONNECTIONS Introduced in 7.30.0. See \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. .IP CURLMOPT_MAXCONNECTS Introduced in 7.16.3. See \fICURLMOPT_MAXCONNECTS(3)\fP. .IP CURLMOPT_PIPELINING Introduced in 7.16.0. See \fICURLMOPT_PIPELINING(3)\fP. .IP CURLMOPT_PIPELINING_SERVER_BL Introduced in 7.30.0. See \fICURLMOPT_PIPELINING_SERVER_BL(3)\fP. .IP CURLMOPT_PIPELINING_SITE_BL Introduced in 7.30.0. See \fICURLMOPT_PIPELINING_SITE_BL(3)\fP. .IP CURLMOPT_PUSHDATA Introduced in 7.44.0. See \fICURLMOPT_PUSHDATA(3)\fP. .IP CURLMOPT_PUSHFUNCTION Introduced in 7.44.0. See \fICURLMOPT_PUSHFUNCTION(3)\fP. .IP CURLMOPT_SOCKETDATA Introduced in 7.15.4. See \fICURLMOPT_SOCKETDATA(3)\fP. .IP CURLMOPT_SOCKETFUNCTION Introduced in 7.15.4. See \fICURLMOPT_SOCKETFUNCTION(3)\fP. .IP CURLMOPT_TIMERDATA Introduced in 7.16.0. See \fICURLMOPT_TIMERDATA(3)\fP. .IP CURLMOPT_TIMERFUNCTION Introduced in 7.16.0. See \fICURLMOPT_TIMERFUNCTION(3)\fP. .IP CURLMSG_DONE Introduced in 7.9.6. See \fIcurl_multi_info_read(3)\fP. .IP CURLMSG_NONE Introduced in 7.9.6. See \fIcurl_multi_info_read(3)\fP. .IP CURLOPT Introduced in 7.69.0. .IP CURLOPT_ABSTRACT_UNIX_SOCKET Introduced in 7.53.0. See \fICURLOPT_ABSTRACT_UNIX_SOCKET(3)\fP. .IP CURLOPT_ACCEPT_ENCODING Introduced in 7.21.6. See \fICURLOPT_ACCEPT_ENCODING(3)\fP. .IP CURLOPT_ACCEPTTIMEOUT_MS Introduced in 7.24.0. See \fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP. .IP CURLOPT_ADDRESS_SCOPE Introduced in 7.19.0. See \fICURLOPT_ADDRESS_SCOPE(3)\fP. .IP CURLOPT_ALTSVC Introduced in 7.64.1. See \fICURLOPT_ALTSVC(3)\fP. .IP CURLOPT_ALTSVC_CTRL Introduced in 7.64.1. See \fICURLOPT_ALTSVC_CTRL(3)\fP. .IP CURLOPT_APPEND Introduced in 7.17.0. See \fICURLOPT_APPEND(3)\fP. .IP CURLOPT_AUTOREFERER Introduced in 7.1. See \fICURLOPT_AUTOREFERER(3)\fP. .IP CURLOPT_AWS_SIGV4 Introduced in 7.75.0. See \fICURLOPT_AWS_SIGV4(3)\fP. .IP CURLOPT_BUFFERSIZE Introduced in 7.10. See \fICURLOPT_BUFFERSIZE(3)\fP. .IP CURLOPT_CAINFO Introduced in 7.4.2. See \fICURLOPT_CAINFO(3)\fP. .IP CURLOPT_CAINFO_BLOB Introduced in 7.77.0. See \fICURLOPT_CAINFO_BLOB(3)\fP. .IP CURLOPT_CAPATH Introduced in 7.9.8. See \fICURLOPT_CAPATH(3)\fP. .IP CURLOPT_CA_CACHE_TIMEOUT Introduced in 7.87.0. See \fICURLOPT_CA_CACHE_TIMEOUT(3)\fP. .IP CURLOPT_CERTINFO Introduced in 7.19.1. See \fICURLOPT_CERTINFO(3)\fP. .IP CURLOPT_CHUNK_BGN_FUNCTION Introduced in 7.21.0. See \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP. .IP CURLOPT_CHUNK_DATA Introduced in 7.21.0. See \fICURLOPT_CHUNK_DATA(3)\fP. .IP CURLOPT_CHUNK_END_FUNCTION Introduced in 7.21.0. See \fICURLOPT_CHUNK_END_FUNCTION(3)\fP. .IP CURLOPT_CLOSEFUNCTION Introduced in 7.7. Deprecated since 7.11.1. .IP CURLOPT_CLOSEPOLICY Introduced in 7.7. Deprecated since 7.16.1. .IP CURLOPT_CLOSESOCKETDATA Introduced in 7.21.7. See \fICURLOPT_CLOSESOCKETDATA(3)\fP. .IP CURLOPT_CLOSESOCKETFUNCTION Introduced in 7.21.7. See \fICURLOPT_CLOSESOCKETFUNCTION(3)\fP. .IP CURLOPT_CONNECT_ONLY Introduced in 7.15.2. See \fICURLOPT_CONNECT_ONLY(3)\fP. .IP CURLOPT_CONNECT_TO Introduced in 7.49.0. See \fICURLOPT_CONNECT_TO(3)\fP. .IP CURLOPT_CONNECTTIMEOUT Introduced in 7.7. See \fICURLOPT_CONNECTTIMEOUT(3)\fP. .IP CURLOPT_CONNECTTIMEOUT_MS Introduced in 7.16.2. See \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP. .IP CURLOPT_CONV_FROM_NETWORK_FUNCTION Introduced in 7.15.4. Deprecated since 7.82.0. .IP CURLOPT_CONV_FROM_UTF8_FUNCTION Introduced in 7.15.4. Deprecated since 7.82.0. .IP CURLOPT_CONV_TO_NETWORK_FUNCTION Introduced in 7.15.4. Deprecated since 7.82.0. .IP CURLOPT_COOKIE Introduced in 7.1. See \fICURLOPT_COOKIE(3)\fP. .IP CURLOPT_COOKIEFILE Introduced in 7.1. See \fICURLOPT_COOKIEFILE(3)\fP. .IP CURLOPT_COOKIEJAR Introduced in 7.9. See \fICURLOPT_COOKIEJAR(3)\fP. .IP CURLOPT_COOKIELIST Introduced in 7.14.1. See \fICURLOPT_COOKIELIST(3)\fP. .IP CURLOPT_COOKIESESSION Introduced in 7.9.7. See \fICURLOPT_COOKIESESSION(3)\fP. .IP CURLOPT_COPYPOSTFIELDS Introduced in 7.17.1. See \fICURLOPT_COPYPOSTFIELDS(3)\fP. .IP CURLOPT_CRLF Introduced in 7.1. See \fICURLOPT_CRLF(3)\fP. .IP CURLOPT_CRLFILE Introduced in 7.19.0. See \fICURLOPT_CRLFILE(3)\fP. .IP CURLOPT_CURLU Introduced in 7.63.0. See \fICURLOPT_CURLU(3)\fP. .IP CURLOPT_CUSTOMREQUEST Introduced in 7.1. See \fICURLOPT_CUSTOMREQUEST(3)\fP. .IP CURLOPT_DEBUGDATA Introduced in 7.9.6. See \fICURLOPT_DEBUGDATA(3)\fP. .IP CURLOPT_DEBUGFUNCTION Introduced in 7.9.6. See \fICURLOPT_DEBUGFUNCTION(3)\fP. .IP CURLOPT_DEFAULT_PROTOCOL Introduced in 7.45.0. See \fICURLOPT_DEFAULT_PROTOCOL(3)\fP. .IP CURLOPT_DIRLISTONLY Introduced in 7.17.0. See \fICURLOPT_DIRLISTONLY(3)\fP. .IP CURLOPT_DISALLOW_USERNAME_IN_URL Introduced in 7.61.0. See \fICURLOPT_DISALLOW_USERNAME_IN_URL(3)\fP. .IP CURLOPT_DNS_CACHE_TIMEOUT Introduced in 7.9.3. See \fICURLOPT_DNS_CACHE_TIMEOUT(3)\fP. .IP CURLOPT_DNS_INTERFACE Introduced in 7.33.0. See \fICURLOPT_DNS_INTERFACE(3)\fP. .IP CURLOPT_DNS_LOCAL_IP4 Introduced in 7.33.0. See \fICURLOPT_DNS_LOCAL_IP4(3)\fP. .IP CURLOPT_DNS_LOCAL_IP6 Introduced in 7.33.0. See \fICURLOPT_DNS_LOCAL_IP6(3)\fP. .IP CURLOPT_DNS_SERVERS Introduced in 7.24.0. See \fICURLOPT_DNS_SERVERS(3)\fP. .IP CURLOPT_DNS_SHUFFLE_ADDRESSES Introduced in 7.60.0. See \fICURLOPT_DNS_SHUFFLE_ADDRESSES(3)\fP. .IP CURLOPT_DNS_USE_GLOBAL_CACHE Introduced in 7.9.3. Deprecated since 7.11.1. .IP CURLOPT_DOH_SSL_VERIFYHOST Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP. .IP CURLOPT_DOH_SSL_VERIFYPEER Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP. .IP CURLOPT_DOH_SSL_VERIFYSTATUS Introduced in 7.76.0. See \fICURLOPT_DOH_SSL_VERIFYSTATUS(3)\fP. .IP CURLOPT_DOH_URL Introduced in 7.62.0. See \fICURLOPT_DOH_URL(3)\fP. .IP CURLOPT_ECH Introduced in 8.8.0. See \fICURLOPT_ECH(3)\fP. .IP CURLOPT_EGDSOCKET Introduced in 7.7. Deprecated since 7.84.0. .IP CURLOPT_ENCODING Introduced in 7.10. Deprecated since 7.21.6. .IP CURLOPT_ERRORBUFFER Introduced in 7.1. See \fICURLOPT_ERRORBUFFER(3)\fP. .IP CURLOPT_EXPECT_100_TIMEOUT_MS Introduced in 7.36.0. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP. .IP CURLOPT_FAILONERROR Introduced in 7.1. See \fICURLOPT_FAILONERROR(3)\fP. .IP CURLOPT_FILE Introduced in 7.1. Deprecated since 7.9.7. .IP CURLOPT_FILETIME Introduced in 7.5. See \fICURLOPT_FILETIME(3)\fP. .IP CURLOPT_FNMATCH_DATA Introduced in 7.21.0. See \fICURLOPT_FNMATCH_DATA(3)\fP. .IP CURLOPT_FNMATCH_FUNCTION Introduced in 7.21.0. See \fICURLOPT_FNMATCH_FUNCTION(3)\fP. .IP CURLOPT_FOLLOWLOCATION Introduced in 7.1. See \fICURLOPT_FOLLOWLOCATION(3)\fP. .IP CURLOPT_FORBID_REUSE Introduced in 7.7. See \fICURLOPT_FORBID_REUSE(3)\fP. .IP CURLOPT_FRESH_CONNECT Introduced in 7.7. See \fICURLOPT_FRESH_CONNECT(3)\fP. .IP CURLOPT_FTP_ACCOUNT Introduced in 7.13.0. See \fICURLOPT_FTP_ACCOUNT(3)\fP. .IP CURLOPT_FTP_ALTERNATIVE_TO_USER Introduced in 7.15.5. See \fICURLOPT_FTP_ALTERNATIVE_TO_USER(3)\fP. .IP CURLOPT_FTP_CREATE_MISSING_DIRS Introduced in 7.10.7. See \fICURLOPT_FTP_CREATE_MISSING_DIRS(3)\fP. .IP CURLOPT_FTP_FILEMETHOD Introduced in 7.15.1. See \fICURLOPT_FTP_FILEMETHOD(3)\fP. .IP CURLOPT_FTP_RESPONSE_TIMEOUT Introduced in 7.10.8. Deprecated since 7.85.0. .IP CURLOPT_FTP_SKIP_PASV_IP Introduced in 7.15.0. See \fICURLOPT_FTP_SKIP_PASV_IP(3)\fP. .IP CURLOPT_FTP_SSL Introduced in 7.11.0. Deprecated since 7.16.4. .IP CURLOPT_FTP_SSL_CCC Introduced in 7.16.1. See \fICURLOPT_FTP_SSL_CCC(3)\fP. .IP CURLOPT_FTP_USE_EPRT Introduced in 7.10.5. See \fICURLOPT_FTP_USE_EPRT(3)\fP. .IP CURLOPT_FTP_USE_EPSV Introduced in 7.9.2. See \fICURLOPT_FTP_USE_EPSV(3)\fP. .IP CURLOPT_FTP_USE_PRET Introduced in 7.20.0. See \fICURLOPT_FTP_USE_PRET(3)\fP. .IP CURLOPT_FTPAPPEND Introduced in 7.1. Deprecated since 7.16.4. .IP CURLOPT_FTPASCII Introduced in 7.1. Deprecated since 7.11.1. .IP CURLOPT_FTPLISTONLY Introduced in 7.1. Deprecated since 7.16.4. .IP CURLOPT_FTPPORT Introduced in 7.1. See \fICURLOPT_FTPPORT(3)\fP. .IP CURLOPT_FTPSSLAUTH Introduced in 7.12.2. See \fICURLOPT_FTPSSLAUTH(3)\fP. .IP CURLOPT_GSSAPI_DELEGATION Introduced in 7.22.0. See \fICURLOPT_GSSAPI_DELEGATION(3)\fP. .IP CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS Introduced in 7.59.0. See \fICURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS(3)\fP. .IP CURLOPT_HAPROXYPROTOCOL Introduced in 7.60.0. See \fICURLOPT_HAPROXYPROTOCOL(3)\fP. .IP CURLOPT_HAPROXY_CLIENT_IP Introduced in 8.2.0. See \fICURLOPT_HAPROXY_CLIENT_IP(3)\fP. .IP CURLOPT_HEADER Introduced in 7.1. See \fICURLOPT_HEADER(3)\fP. .IP CURLOPT_HEADERDATA Introduced in 7.10. See \fICURLOPT_HEADERDATA(3)\fP. .IP CURLOPT_HEADERFUNCTION Introduced in 7.7.2. See \fICURLOPT_HEADERFUNCTION(3)\fP. .IP CURLOPT_HEADEROPT Introduced in 7.37.0. See \fICURLOPT_HEADEROPT(3)\fP. .IP CURLOPT_HSTS Introduced in 7.74.0. See \fICURLOPT_HSTS(3)\fP. .IP CURLOPT_HSTS_CTRL Introduced in 7.74.0. See \fICURLOPT_HSTS_CTRL(3)\fP. .IP CURLOPT_HSTSREADDATA Introduced in 7.74.0. See \fICURLOPT_HSTSREADDATA(3)\fP. .IP CURLOPT_HSTSREADFUNCTION Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. .IP CURLOPT_HSTSWRITEDATA Introduced in 7.74.0. See \fICURLOPT_HSTSWRITEDATA(3)\fP. .IP CURLOPT_HSTSWRITEFUNCTION Introduced in 7.74.0. See \fICURLOPT_HSTSWRITEFUNCTION(3)\fP. .IP CURLOPT_HTTP09_ALLOWED Introduced in 7.64.0. See \fICURLOPT_HTTP09_ALLOWED(3)\fP. .IP CURLOPT_HTTP200ALIASES Introduced in 7.10.3. See \fICURLOPT_HTTP200ALIASES(3)\fP. .IP CURLOPT_HTTP_CONTENT_DECODING Introduced in 7.16.2. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP. .IP CURLOPT_HTTP_TRANSFER_DECODING Introduced in 7.16.2. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP. .IP CURLOPT_HTTP_VERSION Introduced in 7.9.1. See \fICURLOPT_HTTP_VERSION(3)\fP. .IP CURLOPT_HTTPAUTH Introduced in 7.10.6. See \fICURLOPT_HTTPAUTH(3)\fP. .IP CURLOPT_HTTPGET Introduced in 7.8.1. See \fICURLOPT_HTTPGET(3)\fP. .IP CURLOPT_HTTPHEADER Introduced in 7.1. See \fICURLOPT_HTTPHEADER(3)\fP. .IP CURLOPT_HTTPPOST Introduced in 7.1. Deprecated since 7.56.0. .IP CURLOPT_HTTPPROXYTUNNEL Introduced in 7.3. See \fICURLOPT_HTTPPROXYTUNNEL(3)\fP. .IP CURLOPT_HTTPREQUEST Introduced in 7.1. Last used in 7.15.5. .IP CURLOPT_IGNORE_CONTENT_LENGTH Introduced in 7.14.1. See \fICURLOPT_IGNORE_CONTENT_LENGTH(3)\fP. .IP CURLOPT_INFILE Introduced in 7.1. Deprecated since 7.9.7. .IP CURLOPT_INFILESIZE Introduced in 7.1. See \fICURLOPT_INFILESIZE(3)\fP. .IP CURLOPT_INFILESIZE_LARGE Introduced in 7.11.0. See \fICURLOPT_INFILESIZE_LARGE(3)\fP. .IP CURLOPT_INTERFACE Introduced in 7.3. See \fICURLOPT_INTERFACE(3)\fP. .IP CURLOPT_INTERLEAVEDATA Introduced in 7.20.0. See \fICURLOPT_INTERLEAVEDATA(3)\fP. .IP CURLOPT_INTERLEAVEFUNCTION Introduced in 7.20.0. See \fICURLOPT_INTERLEAVEFUNCTION(3)\fP. .IP CURLOPT_IOCTLDATA Introduced in 7.12.3. Deprecated since 7.18.0. .IP CURLOPT_IOCTLFUNCTION Introduced in 7.12.3. Deprecated since 7.18.0. .IP CURLOPT_IPRESOLVE Introduced in 7.10.8. See \fICURLOPT_IPRESOLVE(3)\fP. .IP CURLOPT_ISSUERCERT Introduced in 7.19.0. See \fICURLOPT_ISSUERCERT(3)\fP. .IP CURLOPT_ISSUERCERT_BLOB Introduced in 7.71.0. See \fICURLOPT_ISSUERCERT_BLOB(3)\fP. .IP CURLOPT_KEEP_SENDING_ON_ERROR Introduced in 7.51.0. See \fICURLOPT_KEEP_SENDING_ON_ERROR(3)\fP. .IP CURLOPT_KEYPASSWD Introduced in 7.17.0. See \fICURLOPT_KEYPASSWD(3)\fP. .IP CURLOPT_KRB4LEVEL Introduced in 7.3. Deprecated since 7.17.0. .IP CURLOPT_KRBLEVEL Introduced in 7.16.4. See \fICURLOPT_KRBLEVEL(3)\fP. .IP CURLOPT_LOCALPORT Introduced in 7.15.2. See \fICURLOPT_LOCALPORT(3)\fP. .IP CURLOPT_LOCALPORTRANGE Introduced in 7.15.2. See \fICURLOPT_LOCALPORTRANGE(3)\fP. .IP CURLOPT_LOGIN_OPTIONS Introduced in 7.34.0. See \fICURLOPT_LOGIN_OPTIONS(3)\fP. .IP CURLOPT_LOW_SPEED_LIMIT Introduced in 7.1. See \fICURLOPT_LOW_SPEED_LIMIT(3)\fP. .IP CURLOPT_LOW_SPEED_TIME Introduced in 7.1. See \fICURLOPT_LOW_SPEED_TIME(3)\fP. .IP CURLOPT_MAIL_AUTH Introduced in 7.25.0. See \fICURLOPT_MAIL_AUTH(3)\fP. .IP CURLOPT_MAIL_FROM Introduced in 7.20.0. See \fICURLOPT_MAIL_FROM(3)\fP. .IP CURLOPT_MAIL_RCPT Introduced in 7.20.0. See \fICURLOPT_MAIL_RCPT(3)\fP. .IP CURLOPT_MAIL_RCPT_ALLLOWFAILS Introduced in 7.69.0. Deprecated since 8.2.0. .IP CURLOPT_MAIL_RCPT_ALLOWFAILS Introduced in 8.2.0. See \fICURLOPT_MAIL_RCPT_ALLOWFAILS(3)\fP. .IP CURLOPT_QUICK_EXIT Introduced in 7.87.0. See \fICURLOPT_QUICK_EXIT(3)\fP. .IP CURLOPT_MAX_RECV_SPEED_LARGE Introduced in 7.15.5. See \fICURLOPT_MAX_RECV_SPEED_LARGE(3)\fP. .IP CURLOPT_MAX_SEND_SPEED_LARGE Introduced in 7.15.5. See \fICURLOPT_MAX_SEND_SPEED_LARGE(3)\fP. .IP CURLOPT_MAXAGE_CONN Introduced in 7.65.0. See \fICURLOPT_MAXAGE_CONN(3)\fP. .IP CURLOPT_MAXCONNECTS Introduced in 7.7. See \fICURLOPT_MAXCONNECTS(3)\fP. .IP CURLOPT_MAXFILESIZE Introduced in 7.10.8. See \fICURLOPT_MAXFILESIZE(3)\fP. .IP CURLOPT_MAXFILESIZE_LARGE Introduced in 7.11.0. See \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. .IP CURLOPT_MAXLIFETIME_CONN Introduced in 7.80.0. See \fICURLOPT_MAXLIFETIME_CONN(3)\fP. .IP CURLOPT_MAXREDIRS Introduced in 7.5. See \fICURLOPT_MAXREDIRS(3)\fP. .IP CURLOPT_MIME_OPTIONS Introduced in 7.81.0. See \fICURLOPT_MIME_OPTIONS(3)\fP. .IP CURLOPT_MIMEPOST Introduced in 7.56.0. See \fICURLOPT_MIMEPOST(3)\fP. .IP CURLOPT_MUTE Introduced in 7.1. Deprecated since 7.8. .IP CURLOPT_NETRC Introduced in 7.1. See \fICURLOPT_NETRC(3)\fP. .IP CURLOPT_NETRC_FILE Introduced in 7.11.0. See \fICURLOPT_NETRC_FILE(3)\fP. .IP CURLOPT_NEW_DIRECTORY_PERMS Introduced in 7.16.4. See \fICURLOPT_NEW_DIRECTORY_PERMS(3)\fP. .IP CURLOPT_NEW_FILE_PERMS Introduced in 7.16.4. See \fICURLOPT_NEW_FILE_PERMS(3)\fP. .IP CURLOPT_NOBODY Introduced in 7.1. See \fICURLOPT_NOBODY(3)\fP. .IP CURLOPT_NOPROGRESS Introduced in 7.1. See \fICURLOPT_NOPROGRESS(3)\fP. .IP CURLOPT_NOPROXY Introduced in 7.19.4. See \fICURLOPT_NOPROXY(3)\fP. .IP CURLOPT_NOSIGNAL Introduced in 7.10. See \fICURLOPT_NOSIGNAL(3)\fP. .IP CURLOPT_NOTHING Introduced in 7.1.1. Deprecated since 7.11.1. .IP CURLOPT_OPENSOCKETDATA Introduced in 7.17.1. See \fICURLOPT_OPENSOCKETDATA(3)\fP. .IP CURLOPT_OPENSOCKETFUNCTION Introduced in 7.17.1. See \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. .IP CURLOPT_PASSWDDATA Introduced in 7.4.2. Deprecated since 7.11.1. .IP CURLOPT_PASSWDFUNCTION Introduced in 7.4.2. Deprecated since 7.11.1. .IP CURLOPT_PASSWORD Introduced in 7.19.1. See \fICURLOPT_PASSWORD(3)\fP. .IP CURLOPT_PASV_HOST Introduced in 7.12.1. Deprecated since 7.16.0. .IP CURLOPT_PATH_AS_IS Introduced in 7.42.0. See \fICURLOPT_PATH_AS_IS(3)\fP. .IP CURLOPT_PINNEDPUBLICKEY Introduced in 7.39.0. See \fICURLOPT_PINNEDPUBLICKEY(3)\fP. .IP CURLOPT_PIPEWAIT Introduced in 7.43.0. See \fICURLOPT_PIPEWAIT(3)\fP. .IP CURLOPT_PORT Introduced in 7.1. See \fICURLOPT_PORT(3)\fP. .IP CURLOPT_POST Introduced in 7.1. See \fICURLOPT_POST(3)\fP. .IP CURLOPT_POST301 Introduced in 7.17.1. Deprecated since 7.19.1. .IP CURLOPT_POSTFIELDS Introduced in 7.1. See \fICURLOPT_POSTFIELDS(3)\fP. .IP CURLOPT_POSTFIELDSIZE Introduced in 7.2. See \fICURLOPT_POSTFIELDSIZE(3)\fP. .IP CURLOPT_POSTFIELDSIZE_LARGE Introduced in 7.11.1. See \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. .IP CURLOPT_POSTQUOTE Introduced in 7.1. See \fICURLOPT_POSTQUOTE(3)\fP. .IP CURLOPT_POSTREDIR Introduced in 7.19.1. See \fICURLOPT_POSTREDIR(3)\fP. .IP CURLOPT_PRE_PROXY Introduced in 7.52.0. See \fICURLOPT_PRE_PROXY(3)\fP. .IP CURLOPT_PREQUOTE Introduced in 7.9.5. See \fICURLOPT_PREQUOTE(3)\fP. .IP CURLOPT_PREREQDATA Introduced in 7.80.0. See \fICURLOPT_PREREQDATA(3)\fP. .IP CURLOPT_PREREQFUNCTION Introduced in 7.80.0. See \fICURLOPT_PREREQFUNCTION(3)\fP. .IP CURLOPT_PRIVATE Introduced in 7.10.3. See \fICURLOPT_PRIVATE(3)\fP. .IP CURLOPT_PROGRESSDATA Introduced in 7.1. See \fICURLOPT_PROGRESSDATA(3)\fP. .IP CURLOPT_PROGRESSFUNCTION Introduced in 7.1. Deprecated since 7.32.0. .IP CURLOPT_PROTOCOLS Introduced in 7.19.4. Deprecated since 7.85.0. .IP CURLOPT_PROTOCOLS_STR Introduced in 7.85.0. See \fICURLOPT_PROTOCOLS_STR(3)\fP. .IP CURLOPT_PROXY Introduced in 7.1. See \fICURLOPT_PROXY(3)\fP. .IP CURLOPT_PROXY_CAINFO Introduced in 7.52.0. See \fICURLOPT_PROXY_CAINFO(3)\fP. .IP CURLOPT_PROXY_CAINFO_BLOB Introduced in 7.77.0. See \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP. .IP CURLOPT_PROXY_CAPATH Introduced in 7.52.0. See \fICURLOPT_PROXY_CAPATH(3)\fP. .IP CURLOPT_PROXY_CRLFILE Introduced in 7.52.0. See \fICURLOPT_PROXY_CRLFILE(3)\fP. .IP CURLOPT_PROXY_ISSUERCERT Introduced in 7.71.0. See \fICURLOPT_PROXY_ISSUERCERT(3)\fP. .IP CURLOPT_PROXY_ISSUERCERT_BLOB Introduced in 7.71.0. See \fICURLOPT_PROXY_ISSUERCERT_BLOB(3)\fP. .IP CURLOPT_PROXY_KEYPASSWD Introduced in 7.52.0. See \fICURLOPT_PROXY_KEYPASSWD(3)\fP. .IP CURLOPT_PROXY_PINNEDPUBLICKEY Introduced in 7.52.0. See \fICURLOPT_PROXY_PINNEDPUBLICKEY(3)\fP. .IP CURLOPT_PROXY_SERVICE_NAME Introduced in 7.43.0. See \fICURLOPT_PROXY_SERVICE_NAME(3)\fP. .IP CURLOPT_PROXY_SSL_CIPHER_LIST Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_CIPHER_LIST(3)\fP. .IP CURLOPT_PROXY_SSL_OPTIONS Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_OPTIONS(3)\fP. .IP CURLOPT_PROXY_SSL_VERIFYHOST Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_VERIFYHOST(3)\fP. .IP CURLOPT_PROXY_SSL_VERIFYPEER Introduced in 7.52.0. See \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP. .IP CURLOPT_PROXY_SSLCERT Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLCERT(3)\fP. .IP CURLOPT_PROXY_SSLCERT_BLOB Introduced in 7.71.0. See \fICURLOPT_PROXY_SSLCERT_BLOB(3)\fP. .IP CURLOPT_PROXY_SSLCERTTYPE Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLCERTTYPE(3)\fP. .IP CURLOPT_PROXY_SSLKEY Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLKEY(3)\fP. .IP CURLOPT_PROXY_SSLKEY_BLOB Introduced in 7.71.0. See \fICURLOPT_PROXY_SSLKEY_BLOB(3)\fP. .IP CURLOPT_PROXY_SSLKEYTYPE Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLKEYTYPE(3)\fP. .IP CURLOPT_PROXY_SSLVERSION Introduced in 7.52.0. See \fICURLOPT_PROXY_SSLVERSION(3)\fP. .IP CURLOPT_PROXY_TLS13_CIPHERS Introduced in 7.61.0. See \fICURLOPT_PROXY_TLS13_CIPHERS(3)\fP. .IP CURLOPT_PROXY_TLSAUTH_PASSWORD Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_PASSWORD(3)\fP. .IP CURLOPT_PROXY_TLSAUTH_TYPE Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_TYPE(3)\fP. .IP CURLOPT_PROXY_TLSAUTH_USERNAME Introduced in 7.52.0. See \fICURLOPT_PROXY_TLSAUTH_USERNAME(3)\fP. .IP CURLOPT_PROXY_TRANSFER_MODE Introduced in 7.18.0. See \fICURLOPT_PROXY_TRANSFER_MODE(3)\fP. .IP CURLOPT_PROXYAUTH Introduced in 7.10.7. See \fICURLOPT_PROXYAUTH(3)\fP. .IP CURLOPT_PROXYHEADER Introduced in 7.37.0. See \fICURLOPT_PROXYHEADER(3)\fP. .IP CURLOPT_PROXYPASSWORD Introduced in 7.19.1. See \fICURLOPT_PROXYPASSWORD(3)\fP. .IP CURLOPT_PROXYPORT Introduced in 7.1. See \fICURLOPT_PROXYPORT(3)\fP. .IP CURLOPT_PROXYTYPE Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLOPT_PROXYUSERNAME Introduced in 7.19.1. See \fICURLOPT_PROXYUSERNAME(3)\fP. .IP CURLOPT_PROXYUSERPWD Introduced in 7.1. See \fICURLOPT_PROXYUSERPWD(3)\fP. .IP CURLOPT_PUT Introduced in 7.1. Deprecated since 7.12.1. .IP CURLOPT_QUOTE Introduced in 7.1. See \fICURLOPT_QUOTE(3)\fP. .IP CURLOPT_RANDOM_FILE Introduced in 7.7. Deprecated since 7.84.0. .IP CURLOPT_RANGE Introduced in 7.1. See \fICURLOPT_RANGE(3)\fP. .IP CURLOPT_READDATA Introduced in 7.9.7. See \fICURLOPT_READDATA(3)\fP. .IP CURLOPT_READFUNCTION Introduced in 7.1. See \fICURLOPT_READFUNCTION(3)\fP. .IP CURLOPT_REDIR_PROTOCOLS Introduced in 7.19.4. Deprecated since 7.85.0. .IP CURLOPT_REDIR_PROTOCOLS_STR Introduced in 7.85.0. See \fICURLOPT_REDIR_PROTOCOLS_STR(3)\fP. .IP CURLOPT_REFERER Introduced in 7.1. See \fICURLOPT_REFERER(3)\fP. .IP CURLOPT_REQUEST_TARGET Introduced in 7.55.0. See \fICURLOPT_REQUEST_TARGET(3)\fP. .IP CURLOPT_RESOLVE Introduced in 7.21.3. See \fICURLOPT_RESOLVE(3)\fP. .IP CURLOPT_RESOLVER_START_DATA Introduced in 7.59.0. See \fICURLOPT_RESOLVER_START_DATA(3)\fP. .IP CURLOPT_RESOLVER_START_FUNCTION Introduced in 7.59.0. See \fICURLOPT_RESOLVER_START_FUNCTION(3)\fP. .IP CURLOPT_RESUME_FROM Introduced in 7.1. See \fICURLOPT_RESUME_FROM(3)\fP. .IP CURLOPT_RESUME_FROM_LARGE Introduced in 7.11.0. See \fICURLOPT_RESUME_FROM_LARGE(3)\fP. .IP CURLOPT_RTSP_CLIENT_CSEQ Introduced in 7.20.0. See \fICURLOPT_RTSP_CLIENT_CSEQ(3)\fP. .IP CURLOPT_RTSP_REQUEST Introduced in 7.20.0. See \fICURLOPT_RTSP_REQUEST(3)\fP. .IP CURLOPT_RTSP_SERVER_CSEQ Introduced in 7.20.0. See \fICURLOPT_RTSP_SERVER_CSEQ(3)\fP. .IP CURLOPT_RTSP_SESSION_ID Introduced in 7.20.0. See \fICURLOPT_RTSP_SESSION_ID(3)\fP. .IP CURLOPT_RTSP_STREAM_URI Introduced in 7.20.0. See \fICURLOPT_RTSP_STREAM_URI(3)\fP. .IP CURLOPT_RTSP_TRANSPORT Introduced in 7.20.0. See \fICURLOPT_RTSP_TRANSPORT(3)\fP. .IP CURLOPT_RTSPHEADER Introduced in 7.20.0. See CURLOPT_HTTPHEADER. .IP CURLOPT_SASL_AUTHZID Introduced in 7.66.0. See \fICURLOPT_SASL_AUTHZID(3)\fP. .IP CURLOPT_SASL_IR Introduced in 7.31.0. See \fICURLOPT_SASL_IR(3)\fP. .IP CURLOPT_SEEKDATA Introduced in 7.18.0. See \fICURLOPT_SEEKDATA(3)\fP. .IP CURLOPT_SEEKFUNCTION Introduced in 7.18.0. See \fICURLOPT_SEEKFUNCTION(3)\fP. .IP CURLOPT_SERVER_RESPONSE_TIMEOUT Introduced in 7.20.0. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT(3)\fP. .IP CURLOPT_SERVER_RESPONSE_TIMEOUT_MS Introduced in 8.6.0. See \fICURLOPT_SERVER_RESPONSE_TIMEOUT_MS(3)\fP. .IP CURLOPT_SERVICE_NAME Introduced in 7.43.0. See \fICURLOPT_SERVICE_NAME(3)\fP. .IP CURLOPT_SHARE Introduced in 7.10. See \fICURLOPT_SHARE(3)\fP. .IP CURLOPT_SOCKOPTDATA Introduced in 7.16.0. See \fICURLOPT_SOCKOPTDATA(3)\fP. .IP CURLOPT_SOCKOPTFUNCTION Introduced in 7.16.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. .IP CURLOPT_SOCKS5_AUTH Introduced in 7.55.0. See \fICURLOPT_SOCKS5_AUTH(3)\fP. .IP CURLOPT_SOCKS5_GSSAPI_NEC Introduced in 7.19.4. See \fICURLOPT_SOCKS5_GSSAPI_NEC(3)\fP. .IP CURLOPT_SOCKS5_GSSAPI_SERVICE Introduced in 7.19.4. Deprecated since 7.49.0. .IP CURLOPT_SOURCE_HOST Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SOURCE_PATH Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SOURCE_PORT Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SOURCE_POSTQUOTE Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SOURCE_PREQUOTE Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SOURCE_QUOTE Introduced in 7.13.0. Last used in 7.15.5. .IP CURLOPT_SOURCE_URL Introduced in 7.13.0. Last used in 7.15.5. .IP CURLOPT_SOURCE_USERPWD Introduced in 7.12.1. Last used in 7.15.5. .IP CURLOPT_SSH_AUTH_TYPES Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLOPT_SSH_COMPRESSION Introduced in 7.56.0. See \fICURLOPT_SSH_COMPRESSION(3)\fP. .IP CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 Introduced in 7.17.1. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_MD5(3)\fP. .IP CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 Introduced in 7.80.0. See \fICURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3)\fP. .IP CURLOPT_SSH_HOSTKEYDATA Introduced in 7.84.0. See \fICURLOPT_SSH_HOSTKEYDATA(3)\fP. .IP CURLOPT_SSH_HOSTKEYFUNCTION Introduced in 7.84.0. See \fICURLOPT_SSH_HOSTKEYFUNCTION(3)\fP. .IP CURLOPT_SSH_KEYDATA Introduced in 7.19.6. See \fICURLOPT_SSH_KEYDATA(3)\fP. .IP CURLOPT_SSH_KEYFUNCTION Introduced in 7.19.6. See \fICURLOPT_SSH_KEYFUNCTION(3)\fP. .IP CURLOPT_SSH_KNOWNHOSTS Introduced in 7.19.6. See \fICURLOPT_SSH_KNOWNHOSTS(3)\fP. .IP CURLOPT_SSH_PRIVATE_KEYFILE Introduced in 7.16.1. See \fICURLOPT_SSH_PRIVATE_KEYFILE(3)\fP. .IP CURLOPT_SSH_PUBLIC_KEYFILE Introduced in 7.16.1. See \fICURLOPT_SSH_PUBLIC_KEYFILE(3)\fP. .IP CURLOPT_SSL_CIPHER_LIST Introduced in 7.9. See \fICURLOPT_SSL_CIPHER_LIST(3)\fP. .IP CURLOPT_SSL_CTX_DATA Introduced in 7.10.6. See \fICURLOPT_SSL_CTX_DATA(3)\fP. .IP CURLOPT_SSL_CTX_FUNCTION Introduced in 7.10.6. See \fICURLOPT_SSL_CTX_FUNCTION(3)\fP. .IP CURLOPT_SSL_EC_CURVES Introduced in 7.73.0. See \fICURLOPT_SSL_EC_CURVES(3)\fP. .IP CURLOPT_SSL_ENABLE_ALPN Introduced in 7.36.0. See \fICURLOPT_SSL_ENABLE_ALPN(3)\fP. .IP CURLOPT_SSL_ENABLE_NPN Introduced in 7.36.0. Deprecated since 7.86.0. .IP CURLOPT_SSL_FALSESTART Introduced in 7.42.0. See \fICURLOPT_SSL_FALSESTART(3)\fP. .IP CURLOPT_SSL_OPTIONS Introduced in 7.25.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLOPT_SSL_SESSIONID_CACHE Introduced in 7.16.0. See \fICURLOPT_SSL_SESSIONID_CACHE(3)\fP. .IP CURLOPT_SSL_SIGNATURE_ALGORITHMS Introduced in 8.14.0. See \fICURLOPT_SSL_SIGNATURE_ALGORITHMS(3)\fP. .IP CURLOPT_SSL_VERIFYHOST Introduced in 7.8.1. See \fICURLOPT_SSL_VERIFYHOST(3)\fP. .IP CURLOPT_SSL_VERIFYPEER Introduced in 7.4.2. See \fICURLOPT_SSL_VERIFYPEER(3)\fP. .IP CURLOPT_SSL_VERIFYSTATUS Introduced in 7.41.0. See \fICURLOPT_SSL_VERIFYSTATUS(3)\fP. .IP CURLOPT_SSLCERT Introduced in 7.1. See \fICURLOPT_SSLCERT(3)\fP. .IP CURLOPT_SSLCERT_BLOB Introduced in 7.71.0. See \fICURLOPT_SSLCERT_BLOB(3)\fP. .IP CURLOPT_SSLCERTPASSWD Introduced in 7.1.1. Deprecated since 7.17.0. .IP CURLOPT_SSLCERTTYPE Introduced in 7.9.3. See \fICURLOPT_SSLCERTTYPE(3)\fP. .IP CURLOPT_SSLENGINE Introduced in 7.9.3. See \fICURLOPT_SSLENGINE(3)\fP. .IP CURLOPT_SSLENGINE_DEFAULT Introduced in 7.9.3. See \fICURLOPT_SSLENGINE_DEFAULT(3)\fP. .IP CURLOPT_SSLKEY Introduced in 7.9.3. See \fICURLOPT_SSLKEY(3)\fP. .IP CURLOPT_SSLKEY_BLOB Introduced in 7.71.0. See \fICURLOPT_SSLKEY_BLOB(3)\fP. .IP CURLOPT_SSLKEYPASSWD Introduced in 7.9.3. Deprecated since 7.17.0. .IP CURLOPT_SSLKEYTYPE Introduced in 7.9.3. See \fICURLOPT_SSLKEYTYPE(3)\fP. .IP CURLOPT_SSLVERSION Introduced in 7.1. See \fICURLOPT_SSLVERSION(3)\fP. .IP CURLOPT_STDERR Introduced in 7.1. See \fICURLOPT_STDERR(3)\fP. .IP CURLOPT_STREAM_DEPENDS Introduced in 7.46.0. See \fICURLOPT_STREAM_DEPENDS(3)\fP. .IP CURLOPT_STREAM_DEPENDS_E Introduced in 7.46.0. See \fICURLOPT_STREAM_DEPENDS_E(3)\fP. .IP CURLOPT_STREAM_WEIGHT Introduced in 7.46.0. See \fICURLOPT_STREAM_WEIGHT(3)\fP. .IP CURLOPT_SUPPRESS_CONNECT_HEADERS Introduced in 7.54.0. See \fICURLOPT_SUPPRESS_CONNECT_HEADERS(3)\fP. .IP CURLOPT_TCP_FASTOPEN Introduced in 7.49.0. See \fICURLOPT_TCP_FASTOPEN(3)\fP. .IP CURLOPT_TCP_KEEPALIVE Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPALIVE(3)\fP. .IP CURLOPT_TCP_KEEPIDLE Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPIDLE(3)\fP. .IP CURLOPT_TCP_KEEPINTVL Introduced in 7.25.0. See \fICURLOPT_TCP_KEEPINTVL(3)\fP. .IP CURLOPT_TCP_KEEPCNT Introduced in 8.9.0. See \fICURLOPT_TCP_KEEPCNT(3)\fP. .IP CURLOPT_TCP_NODELAY Introduced in 7.11.2. See \fICURLOPT_TCP_NODELAY(3)\fP. .IP CURLOPT_TELNETOPTIONS Introduced in 7.7. See \fICURLOPT_TELNETOPTIONS(3)\fP. .IP CURLOPT_TFTP_BLKSIZE Introduced in 7.19.4. See \fICURLOPT_TFTP_BLKSIZE(3)\fP. .IP CURLOPT_TFTP_NO_OPTIONS Introduced in 7.48.0. See \fICURLOPT_TFTP_NO_OPTIONS(3)\fP. .IP CURLOPT_TIMECONDITION Introduced in 7.1. See \fICURLOPT_TIMECONDITION(3)\fP. .IP CURLOPT_TIMEOUT Introduced in 7.1. See \fICURLOPT_TIMEOUT(3)\fP. .IP CURLOPT_TIMEOUT_MS Introduced in 7.16.2. See \fICURLOPT_TIMEOUT_MS(3)\fP. .IP CURLOPT_TIMEVALUE Introduced in 7.1. See \fICURLOPT_TIMEVALUE(3)\fP. .IP CURLOPT_TIMEVALUE_LARGE Introduced in 7.59.0. See \fICURLOPT_TIMEVALUE_LARGE(3)\fP. .IP CURLOPT_TLS13_CIPHERS Introduced in 7.61.0. See \fICURLOPT_TLS13_CIPHERS(3)\fP. .IP CURLOPT_TLSAUTH_PASSWORD Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_PASSWORD(3)\fP. .IP CURLOPT_TLSAUTH_TYPE Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_TYPE(3)\fP. .IP CURLOPT_TLSAUTH_USERNAME Introduced in 7.21.4. See \fICURLOPT_TLSAUTH_USERNAME(3)\fP. .IP CURLOPT_TRAILERDATA Introduced in 7.64.0. See \fICURLOPT_TRAILERDATA(3)\fP. .IP CURLOPT_TRAILERFUNCTION Introduced in 7.64.0. See \fICURLOPT_TRAILERFUNCTION(3)\fP. .IP CURLOPT_TRANSFER_ENCODING Introduced in 7.21.6. See \fICURLOPT_TRANSFER_ENCODING(3)\fP. .IP CURLOPT_TRANSFERTEXT Introduced in 7.1.1. See \fICURLOPT_TRANSFERTEXT(3)\fP. .IP CURLOPT_UNIX_SOCKET_PATH Introduced in 7.40.0. See \fICURLOPT_UNIX_SOCKET_PATH(3)\fP. .IP CURLOPT_UNRESTRICTED_AUTH Introduced in 7.10.4. See \fICURLOPT_UNRESTRICTED_AUTH(3)\fP. .IP CURLOPT_UPKEEP_INTERVAL_MS Introduced in 7.62.0. See \fICURLOPT_UPKEEP_INTERVAL_MS(3)\fP. .IP CURLOPT_UPLOAD Introduced in 7.1. See \fICURLOPT_UPLOAD(3)\fP. .IP CURLOPT_UPLOAD_BUFFERSIZE Introduced in 7.62.0. See \fICURLOPT_UPLOAD_BUFFERSIZE(3)\fP. .IP CURLOPT_UPLOAD_FLAGS Introduced in 8.13.0. See \fICURLOPT_UPLOAD_FLAGS(3)\fP. .IP CURLOPT_URL Introduced in 7.1. See \fICURLOPT_URL(3)\fP. .IP CURLOPT_USE_SSL Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLOPT_USERAGENT Introduced in 7.1. See \fICURLOPT_USERAGENT(3)\fP. .IP CURLOPT_USERNAME Introduced in 7.19.1. See \fICURLOPT_USERNAME(3)\fP. .IP CURLOPT_USERPWD Introduced in 7.1. See \fICURLOPT_USERPWD(3)\fP. .IP CURLOPT_VERBOSE Introduced in 7.1. See \fICURLOPT_VERBOSE(3)\fP. .IP CURLOPT_WILDCARDMATCH Introduced in 7.21.0. See \fICURLOPT_WILDCARDMATCH(3)\fP. .IP CURLOPT_WRITEDATA Introduced in 7.9.7. See \fICURLOPT_WRITEDATA(3)\fP. .IP CURLOPT_WRITEFUNCTION Introduced in 7.1. See \fICURLOPT_WRITEFUNCTION(3)\fP. .IP CURLOPT_WRITEHEADER Introduced in 7.1. See CURLOPT_HEADERDATA. .IP CURLOPT_WRITEINFO Introduced in 7.1. .IP CURLOPT_WS_OPTIONS Introduced in 7.86.0. See \fICURLOPT_WS_OPTIONS(3)\fP. .IP CURLOPT_XFERINFODATA Introduced in 7.32.0. See \fICURLOPT_XFERINFODATA(3)\fP. .IP CURLOPT_XFERINFOFUNCTION Introduced in 7.32.0. See \fICURLOPT_XFERINFOFUNCTION(3)\fP. .IP CURLOPT_XOAUTH2_BEARER Introduced in 7.33.0. See \fICURLOPT_XOAUTH2_BEARER(3)\fP. .IP CURLOPTDEPRECATED Introduced in 7.87.0. .IP CURLOPTTYPE_BLOB Introduced in 7.71.0. .IP CURLOPTTYPE_CBPOINT Introduced in 7.73.0. .IP CURLOPTTYPE_FUNCTIONPOINT Introduced in 7.1. .IP CURLOPTTYPE_LONG Introduced in 7.1. .IP CURLOPTTYPE_OBJECTPOINT Introduced in 7.1. .IP CURLOPTTYPE_OFF_T Introduced in 7.11.0. .IP CURLOPTTYPE_SLISTPOINT Introduced in 7.65.2. .IP CURLOPTTYPE_STRINGPOINT Introduced in 7.46.0. .IP CURLOPTTYPE_VALUES Introduced in 7.73.0. .IP CURLOT_BLOB Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_CBPTR Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_FLAG_ALIAS Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_FUNCTION Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_LONG Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_OBJECT Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_OFF_T Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_SLIST Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_STRING Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLOT_VALUES Introduced in 7.73.0. See \fIcurl_easy_option_next(3)\fP. .IP CURLPAUSE_ALL Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPAUSE_CONT Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPAUSE_RECV Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPAUSE_RECV_CONT Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPAUSE_SEND Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPAUSE_SEND_CONT Introduced in 7.18.0. See \fIcurl_easy_pause(3)\fP. .IP CURLPIPE_HTTP1 Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. .IP CURLPIPE_MULTIPLEX Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. .IP CURLPIPE_NOTHING Introduced in 7.43.0. See \fICURLMOPT_PIPELINING(3)\fP. .IP CURLPROTO_ALL Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_DICT Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_FILE Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_FTP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_FTPS Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_GOPHER Introduced in 7.21.2. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_GOPHERS Introduced in 7.75.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_HTTP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_HTTPS Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_IMAP Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_IMAPS Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_LDAP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_LDAPS Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_MQTT Introduced in 7.71.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_POP3 Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_POP3S Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMP Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMPE Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMPS Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMPT Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMPTE Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTMPTS Introduced in 7.21.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_RTSP Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SCP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SFTP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SMB Introduced in 7.40.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SMBS Introduced in 7.40.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SMTP Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_SMTPS Introduced in 7.20.0. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_TELNET Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROTO_TFTP Introduced in 7.19.4. See \fICURLINFO_PROTOCOL(3)\fP. .IP CURLPROXY_HTTP Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_HTTP_1_0 Introduced in 7.19.4. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_HTTPS Introduced in 7.52.0. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_HTTPS2 Introduced in 8.1.0. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_SOCKS4 Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_SOCKS4A Introduced in 7.18.0. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_SOCKS5 Introduced in 7.10. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPROXY_SOCKS5_HOSTNAME Introduced in 7.18.0. See \fICURLOPT_PROXYTYPE(3)\fP. .IP CURLPX_BAD_ADDRESS_TYPE Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_BAD_VERSION Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_CLOSED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_GSSAPI Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_GSSAPI_PERMSG Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_GSSAPI_PROTECTION Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_IDENTD Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_IDENTD_DIFFER Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_LONG_HOSTNAME Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_LONG_PASSWD Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_LONG_USER Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_NO_AUTH Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_OK Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_RECV_ADDRESS Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_RECV_AUTH Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_RECV_CONNECT Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_RECV_REQACK Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_ADDRESS_TYPE_NOT_SUPPORTED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_COMMAND_NOT_SUPPORTED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_CONNECTION_REFUSED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_GENERAL_SERVER_FAILURE Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_HOST_UNREACHABLE Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_NETWORK_UNREACHABLE Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_NOT_ALLOWED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_TTL_EXPIRED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REPLY_UNASSIGNED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_REQUEST_FAILED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_RESOLVE_HOST Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_SEND_AUTH Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_SEND_CONNECT Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_SEND_REQUEST Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_UNKNOWN_FAIL Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_UNKNOWN_MODE Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLPX_USER_REJECTED Introduced in 7.73.0. See \fICURLINFO_PROXY_ERROR(3)\fP. .IP CURLSHE_BAD_OPTION Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. .IP CURLSHE_IN_USE Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. .IP CURLSHE_INVALID Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. .IP CURLSHE_NOMEM Introduced in 7.12.0. See \fIlibcurl\-errors(3)\fP. .IP CURLSHE_NOT_BUILT_IN Introduced in 7.23.0. See \fIlibcurl\-errors(3)\fP. .IP CURLSHE_OK Introduced in 7.10.3. See \fIlibcurl\-errors(3)\fP. .IP CURLSHOPT_LOCKFUNC Introduced in 7.10.3. See \fICURLSHOPT_LOCKFUNC(3)\fP. .IP CURLSHOPT_NONE Introduced in 7.10.3. See \fIcurl_share_setopt(3)\fP. .IP CURLSHOPT_SHARE Introduced in 7.10.3. See \fICURLSHOPT_SHARE(3)\fP. .IP CURLSHOPT_UNLOCKFUNC Introduced in 7.10.3. See \fICURLSHOPT_UNLOCKFUNC(3)\fP. .IP CURLSHOPT_UNSHARE Introduced in 7.10.3. See \fICURLSHOPT_UNSHARE(3)\fP. .IP CURLSHOPT_USERDATA Introduced in 7.10.3. See \fICURLSHOPT_USERDATA(3)\fP. .IP CURLSOCKTYPE_ACCEPT Introduced in 7.28.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. .IP CURLSOCKTYPE_IPCXN Introduced in 7.16.0. See \fICURLOPT_SOCKOPTFUNCTION(3)\fP. .IP CURLSSH_AUTH_AGENT Introduced in 7.28.0. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_ANY Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_DEFAULT Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_GSSAPI Introduced in 7.58.0. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_HOST Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_KEYBOARD Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_NONE Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_PASSWORD Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSH_AUTH_PUBLICKEY Introduced in 7.16.1. See \fICURLOPT_SSH_AUTH_TYPES(3)\fP. .IP CURLSSLBACKEND_AWSLC Introduced in 8.1.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_AXTLS Introduced in 7.38.0. Deprecated since 7.61.0. .IP CURLSSLBACKEND_BEARSSL Introduced in 7.68.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_BORINGSSL Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_CYASSL Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_DARWINSSL Introduced in 7.34.0. Deprecated since 7.64.1. .IP CURLSSLBACKEND_GNUTLS Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_GSKIT Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_LIBRESSL Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_MBEDTLS Introduced in 7.46.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_MESALINK Introduced in 7.62.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_NONE Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_NSS Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_OPENSSL Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_POLARSSL Introduced in 7.34.0. Deprecated since 7.69.0. .IP CURLSSLBACKEND_QSOSSL Introduced in 7.34.0. Last used in 7.38.0. .IP CURLSSLBACKEND_RUSTLS Introduced in 7.76.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_SCHANNEL Introduced in 7.34.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_SECURETRANSPORT Introduced in 7.64.1. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLBACKEND_WOLFSSL Introduced in 7.49.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLOPT_ALLOW_BEAST Introduced in 7.25.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_AUTO_CLIENT_CERT Introduced in 7.77.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_NATIVE_CA Introduced in 7.71.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_NO_PARTIALCHAIN Introduced in 7.68.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_NO_REVOKE Introduced in 7.44.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_REVOKE_BEST_EFFORT Introduced in 7.70.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLOPT_EARLYDATA Introduced in 8.11.0. See \fICURLOPT_SSL_OPTIONS(3)\fP. .IP CURLSSLSET_NO_BACKENDS Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLSET_OK Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLSET_TOO_LATE Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSSLSET_UNKNOWN_BACKEND Introduced in 7.56.0. See \fIcurl_global_sslset(3)\fP. .IP CURLSTS_DONE Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. .IP CURLSTS_FAIL Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. .IP CURLSTS_OK Introduced in 7.74.0. See \fICURLOPT_HSTSREADFUNCTION(3)\fP. .IP CURLU_ALLOW_SPACE Introduced in 7.78.0. See \fIcurl_url_get(3)\fP. .IP CURLU_APPENDQUERY Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_DEFAULT_PORT Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_DEFAULT_SCHEME Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_DISALLOW_USER Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_GET_EMPTY Introduced in 8.8.0. See \fIcurl_url_get(3)\fP. .IP CURLU_GUESS_SCHEME Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_NO_AUTHORITY Introduced in 7.67.0. See \fIcurl_url_get(3)\fP. .IP CURLU_NO_DEFAULT_PORT Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_NO_GUESS_SCHEME Introduced in 8.9.0. See \fIcurl_url_get(3)\fP. .IP CURLU_NON_SUPPORT_SCHEME Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_PATH_AS_IS Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_PUNY2IDN Introduced in 8.3.0. See \fIcurl_url_get(3)\fP. .IP CURLU_PUNYCODE Introduced in 7.88.0. See \fIcurl_url_get(3)\fP. .IP CURLU_URLDECODE Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLU_URLENCODE Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUE_BAD_FILE_URL Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_FRAGMENT Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_HANDLE Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_HOSTNAME Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_IPV6 Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_LOGIN Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_PARTPOINTER Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_PASSWORD Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_PATH Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_PORT_NUMBER Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_QUERY Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_SCHEME Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_SLASHES Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_BAD_USER Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_LACKS_IDN Introduced in 7.88.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_MALFORMED_INPUT Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_FRAGMENT Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_HOST Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_OPTIONS Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_PASSWORD Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_PORT Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_QUERY Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_SCHEME Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_USER Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_NO_ZONEID Introduced in 7.81.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_OK Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_OUT_OF_MEMORY Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_TOO_LARGE Introduced in 8.6.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_UNKNOWN_PART Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_UNSUPPORTED_SCHEME Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_URLDECODE Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUE_USER_NOT_ALLOWED Introduced in 7.62.0. See \fIlibcurl\-errors(3)\fP. .IP CURLUPART_FRAGMENT Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_HOST Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_OPTIONS Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_PASSWORD Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_PATH Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_PORT Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_QUERY Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_SCHEME Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_URL Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_USER Introduced in 7.62.0. See \fIcurl_url_get(3)\fP. .IP CURLUPART_ZONEID Introduced in 7.65.0. See \fIcurl_url_get(3)\fP. .IP CURLULFLAG_ANSWERED Introduced in 8.13.0. .IP CURLULFLAG_DELETED Introduced in 8.13.0. .IP CURLULFLAG_DRAFT Introduced in 8.13.0. .IP CURLULFLAG_FLAGGED Introduced in 8.13.0. .IP CURLULFLAG_SEEN Introduced in 8.13.0. .IP CURLUSESSL_ALL Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLUSESSL_CONTROL Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLUSESSL_NONE Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLUSESSL_TRY Introduced in 7.17.0. See \fICURLOPT_USE_SSL(3)\fP. .IP CURLVERSION_EIGHTH Introduced in 7.72.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_ELEVENTH Introduced in 7.87.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_FIFTH Introduced in 7.57.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_FIRST Introduced in 7.10. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_FOURTH Introduced in 7.16.1. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_NINTH Introduced in 7.75.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_NOW Introduced in 7.10. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_SECOND Introduced in 7.11.1. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_SEVENTH Introduced in 7.70.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_SIXTH Introduced in 7.66.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_TENTH Introduced in 7.77.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_THIRD Introduced in 7.12.0. See \fIcurl_version_info(3)\fP. .IP CURLVERSION_TWELFTH Introduced in 8.8.0. See \fIcurl_version_info(3)\fP. .IP CURLWARNING Introduced in 7.66.0. .IP CURLWS_BINARY Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_CLOSE Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_CONT Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_NOAUTOPONG Introduced in 8.14.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_OFFSET Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_PING Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_PONG Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_RAW_MODE Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .IP CURLWS_TEXT Introduced in 7.86.0. See \fIcurl_ws_send(3)\fP. .SH SEE ALSO .BR libcurl (3), .BR libcurl-easy (3), .BR libcurl-multi (3), .BR libcurl-security (3), .BR libcurl-thread (3)	84.96 KB	2025-07-08 09:41
📄 libcurl-thread.3 .\" generated by cd2nroff 0.1 from libcurl-thread.md .TH libcurl-thread 3 "2025-06-27" libcurl .SH NAME libcurl\-thread \- libcurl thread safety .SH Multi-threading with libcurl libcurl is thread safe but has no internal thread synchronization. You may have to provide your own locking should you meet any of the thread safety exceptions below. .SH Handles You must \fBnever\fP share the same handle in multiple threads. You can pass the handles around among threads, but you must never use a single handle from more than one thread at any given time. .SH Shared objects You can share certain data between multiple handles by using the share interface but you must provide your own locking and set \fIcurl_share_setopt(3)\fP CURLSHOPT_LOCKFUNC and CURLSHOPT_UNLOCKFUNC. Note that some items are specifically documented as not thread\-safe in the share API (the connection pool and HSTS cache for example). .SH TLS All current TLS libraries libcurl supports are thread\-safe. .IP OpenSSL OpenSSL 1.1.0+ can be safely used in multi\-threaded applications provided that support for the underlying OS threading API is built\-in. For older versions of OpenSSL, the user must set mutex callbacks. libcurl may not be able to fully clean up after multi\-threaded OpenSSL depending on how OpenSSL was built and loaded as a library. It is possible in some rare circumstances a memory leak could occur unless you implement your own OpenSSL thread cleanup. For example, on Windows if both libcurl and OpenSSL are linked statically to a DLL or application then OpenSSL may leak memory unless the DLL or application calls OPENSSL_thread_stop() before each thread terminates. If OpenSSL is built as a DLL then it does this cleanup automatically and there is no leak. If libcurl is built as a DLL and OpenSSL is linked statically to it then libcurl does this cleanup automatically and there is no leak (added in libcurl 8.8.0). Please review the OpenSSL documentation for a full list of circumstances: https://docs.openssl.org/3.0/man3/OPENSSL_init_crypto/#notes .SH Signals Signals are used for timing out name resolves (during DNS lookup) \- when built without using either the c\-ares or threaded resolver backends. On systems that have a signal concept. When using multiple threads you should set the \fICURLOPT_NOSIGNAL(3)\fP option to 1L for all handles. Everything works fine except that timeouts cannot be honored during DNS lookups \- which you can work around by building libcurl with c\-ares or threaded\-resolver support. c\-ares is a library that provides asynchronous name resolves. On some platforms, libcurl simply cannot function properly multi\-threaded unless the \fICURLOPT_NOSIGNAL(3)\fP option is set. When \fICURLOPT_NOSIGNAL(3)\fP is set to 1L, your application needs to deal with the risk of a SIGPIPE (that at least the OpenSSL backend can trigger). Note that setting \fICURLOPT_NOSIGNAL(3)\fP to 0L does not work in a threaded situation as there is a race condition where libcurl risks restoring the former signal handler while another thread should still ignore it. .SH Name resolving The \fBgethostbyname\fP or \fBgetaddrinfo\fP and other name resolving system calls used by libcurl are provided by your operating system and must be thread safe. It is important that libcurl can find and use thread safe versions of these and other system calls, as otherwise it cannot function fully thread safe. Some operating systems are known to have faulty thread implementations. We have previously received problem reports on BSD (at least in the past, they may be working fine these days). Some operating systems that are known to have solid and working thread support are Linux, Solaris and Windows. .SH curl_global_ functions These functions are thread\-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the \fBCURL_VERSION_THREADSAFE\fP feature bit set (most platforms). If these functions are not thread\-safe and you are using libcurl with multiple threads it is especially important that before use you call \fIcurl_global_init(3)\fP or \fIcurl_global_init_mem(3)\fP to explicitly initialize the library and its dependents, rather than rely on the "lazy" fail\-safe initialization that takes place the first time \fIcurl_easy_init(3)\fP is called. For an in\-depth explanation refer to \fIlibcurl(3)\fP section \fBGLOBAL CONSTANTS\fP. .SH Memory functions These functions, provided either by your operating system or your own replacements, must be thread safe. You can use \fIcurl_global_init_mem(3)\fP to set your own replacement memory functions. .SH Non-safe functions \fICURLOPT_DNS_USE_GLOBAL_CACHE(3)\fP is not thread\-safe. \fIcurl_version_info(3)\fP is not thread\-safe before libcurl initialization. .SH SEE ALSO .BR libcurl-security (3)	4.67 KB	2025-07-08 09:41
📄 libcurl-tutorial.3 .\" generated by cd2nroff 0.1 from libcurl-tutorial.md .TH libcurl-tutorial 3 "2025-06-27" libcurl .SH NAME libcurl\-tutorial \- libcurl programming tutorial .SH Objective This document attempts to describe the general principles and some basic approaches to consider when programming with libcurl. The text focuses on the C interface but should apply fairly well on other language bindings as well as they usually follow the C API pretty closely. This document refers to \(aqthe user\(aq as the person writing the source code that uses libcurl. That would probably be you or someone in your position. What is generally referred to as \(aqthe program\(aq is the collected source code that you write that is using libcurl for transfers. The program is outside libcurl and libcurl is outside of the program. To get more details on all options and functions described herein, please refer to their respective man pages. .SH Building There are many different ways to build C programs. This chapter assumes a Unix style build process. If you use a different build system, you can still read this to get general information that may apply to your environment as well. .IP "Compiling the Program" Your compiler needs to know where the libcurl headers are located. Therefore you must set your compiler\(aqs include path to point to the directory where you installed them. The \(aqcurl\-config\(aq[3] tool can be used to get this information: .nf $ curl-config --cflags .fi .IP "Linking the Program with libcurl" When having compiled the program, you need to link your object files to create a single executable. For that to succeed, you need to link with libcurl and possibly also with other libraries that libcurl itself depends on. Like the OpenSSL libraries, but even some standard OS libraries may be needed on the command line. To figure out which flags to use, once again the \(aqcurl\-config\(aq tool comes to the rescue: .nf $ curl-config --libs .fi .IP "SSL or Not" libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL\-based transfers, like HTTPS and FTPS. If a supported SSL library was detected properly at build\-time, libcurl is built with SSL support. To figure out if an installed libcurl has been built with SSL support enabled, use \fIcurl\-config\fP like this: .nf $ curl-config --feature .fi If SSL is supported, the keyword \fISSL\fP is written to stdout, possibly together with a other features that could be either on or off on for different libcurls. See also the "Features libcurl Provides" further down. .IP "autoconf macro" When you write your configure script to detect libcurl and setup variables accordingly, we offer a macro that probably does everything you need in this area. See docs/libcurl/libcurl.m4 file \- it includes docs on how to use it. .SH Portable Code in a Portable World The people behind libcurl have put a considerable effort to make libcurl work on a large amount of different operating systems and environments. You program libcurl the same way on all platforms that libcurl runs on. There are only a few minor details that differ. If you just make sure to write your code portable enough, you can create a portable program. libcurl should not stop you from that. .SH Global Preparation The program must initialize some of the libcurl functionality globally. That means it should be done exactly once, no matter how many times you intend to use the library. Once for your program\(aqs entire life time. This is done using .nf curl_global_init() .fi and it takes one parameter which is a bit pattern that tells libcurl what to initialize. Using \fICURL_GLOBAL_ALL\fP makes it initialize all known internal sub modules, and might be a good default option. The current two bits that are specified are: .IP CURL_GLOBAL_WIN32 which only does anything on Windows machines. When used on a Windows machine, it makes libcurl initialize the Win32 socket stuff. Without having that initialized properly, your program cannot use sockets properly. You should only do this once for each application, so if your program already does this or of another library in use does it, you should not tell libcurl to do this as well. .IP CURL_GLOBAL_SSL which only does anything on libcurls compiled and built SSL\-enabled. On these systems, this makes libcurl initialize the SSL library properly for this application. This only needs to be done once for each application so if your program or another library already does this, this bit should not be needed. libcurl has a default protection mechanism that detects if \fIcurl_global_init(3)\fP has not been called by the time \fIcurl_easy_perform(3)\fP is called and if that is the case, libcurl runs the function itself with a guessed bit pattern. Please note that depending solely on this is not considered nice nor good. When the program no longer uses libcurl, it should call \fIcurl_global_cleanup(3)\fP, which is the opposite of the init call. It performs the reversed operations to cleanup the resources the \fIcurl_global_init(3)\fP call initialized. Repeated calls to \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP should be avoided. They should only be called once each. .SH Features libcurl Provides It is considered best\-practice to determine libcurl features at runtime rather than at build\-time (if possible of course). By calling \fIcurl_version_info(3)\fP and checking out the details of the returned struct, your program can figure out exactly what the currently running libcurl supports. .SH Two Interfaces libcurl first introduced the so called easy interface. All operations in the easy interface are prefixed with \(aqcurl_easy\(aq. The easy interface lets you do single transfers with a synchronous and blocking function call. libcurl also offers another interface that allows multiple simultaneous transfers in a single thread, the so called multi interface. More about that interface is detailed in a separate chapter further down. You still need to understand the easy interface first, so please continue reading for better understanding. .SH Handle the Easy libcurl To use the easy interface, you must first create yourself an easy handle. You need one handle for each easy session you want to perform. Basically, you should use one handle for every thread you plan to use for transferring. You must never share the same handle in multiple threads. Get an easy handle with .nf handle = curl_easy_init(); .fi It returns an easy handle. Using that you proceed to the next step: setting up your preferred actions. A handle is just a logic entity for the upcoming transfer or series of transfers. You set properties and options for this handle using \fIcurl_easy_setopt(3)\fP. They control how the subsequent transfer or transfers using this handle are made. Options remain set in the handle until set again to something different. They are sticky. Multiple requests using the same handle use the same options. If you at any point would like to blank all previously set options for a single easy handle, you can call \fIcurl_easy_reset(3)\fP and you can also make a clone of an easy handle (with all its set options) using \fIcurl_easy_duphandle(3)\fP. Many of the options you set in libcurl are "strings", pointers to data terminated with a zero byte. When you set strings with \fIcurl_easy_setopt(3)\fP, libcurl makes its own copy so that they do not need to be kept around in your application after being set[4]. One of the most basic properties to set in the handle is the URL. You set your preferred URL to transfer with \fICURLOPT_URL(3)\fP in a manner similar to: .nf curl_easy_setopt(handle, CURLOPT_URL, "http://example.com/"); .fi Let\(aqs assume for a while that you want to receive data as the URL identifies a remote resource you want to get here. Since you write a sort of application that needs this transfer, I assume that you would like to get the data passed to you directly instead of simply getting it passed to stdout. So, you write your own function that matches this prototype: .nf size_t write_data(void buffer, size_t size, size_t nmemb, void userp); .fi You tell libcurl to pass all data to this function by issuing a function similar to this: .nf curl_easy_setopt(handle, CURLOPT_WRITEFUNCTION, write_data); .fi You can control what data your callback function gets in the fourth argument by setting another property: .nf curl_easy_setopt(handle, CURLOPT_WRITEDATA, &internal_struct); .fi Using that property, you can easily pass local data between your application and the function that gets invoked by libcurl. libcurl itself does not touch the data you pass with \fICURLOPT_WRITEDATA(3)\fP. libcurl offers its own default internal callback that takes care of the data if you do not set the callback with \fICURLOPT_WRITEFUNCTION(3)\fP. It simply outputs the received data to stdout. You can have the default callback write the data to a different file handle by passing a \(aqFILE \(aq to a file opened for writing with the \fICURLOPT_WRITEDATA(3)\fP option. Now, we need to take a step back and take a deep breath. Here is one of those rare platform\-dependent nitpicks. Did you spot it? On some platforms[2], libcurl is not able to operate on file handles opened by the program. Therefore, if you use the default callback and pass in an open file handle with \fICURLOPT_WRITEDATA(3)\fP, libcurl crashes. You should avoid this to make your program run fine virtually everywhere. (\fICURLOPT_WRITEDATA(3)\fP was formerly known as \fICURLOPT_FILE\fP. Both names still work and do the same thing). If you are using libcurl as a Windows DLL, you MUST use the \fICURLOPT_WRITEFUNCTION(3)\fP if you set \fICURLOPT_WRITEDATA(3)\fP \- or experience crashes. There are of course many more options you can set, and we get back to a few of them later. Let\(aqs instead continue to the actual transfer: .nf success = curl_easy_perform(handle); .fi \fIcurl_easy_perform(3)\fP connects to the remote site, does the necessary commands and performs the transfer. Whenever it receives data, it calls the callback function we previously set. The function may get one byte at a time, or it may get many kilobytes at once. libcurl delivers as much as possible as often as possible. Your callback function should return the number of bytes it "took care of". If that is not the same amount of bytes that was passed to it, libcurl aborts the operation and returns with an error code. When the transfer is complete, the function returns a return code that informs you if it succeeded in its mission or not. If a return code is not enough for you, you can use the \fICURLOPT_ERRORBUFFER(3)\fP to point libcurl to a buffer of yours where it stores a human readable error message as well. If you then want to transfer another file, the handle is ready to be used again. It is even preferred and encouraged that you reuse an existing handle if you intend to make another transfer. libcurl then attempts to reuse a previous connection. For some protocols, downloading a file can involve a complicated process of logging in, setting the transfer mode, changing the current directory and finally transferring the file data. libcurl takes care of all that complication for you. Given simply the URL to a file, libcurl takes care of all the details needed to get the file moved from one machine to another. .SH Multi-threading Issues libcurl is thread safe but there are a few exceptions. Refer to \fIlibcurl\-thread(3)\fP for more information. .SH When It does not Work There are times when the transfer fails for some reason. You might have set the wrong libcurl option or misunderstood what the libcurl option actually does, or the remote server might return non\-standard replies that confuse the library which then confuses your program. There is one golden rule when these things occur: set the \fICURLOPT_VERBOSE(3)\fP option to 1. it causes the library to spew out the entire protocol details it sends, some internal info and some received protocol data as well (especially when using FTP). If you are using HTTP, adding the headers in the received output to study is also a clever way to get a better understanding why the server behaves the way it does. Include headers in the normal body output with \fICURLOPT_HEADER(3)\fP set 1. Of course, there are bugs left. We need to know about them to be able to fix them, so we are quite dependent on your bug reports. When you do report suspected bugs in libcurl, please include as many details as you possibly can: a protocol dump that \fICURLOPT_VERBOSE(3)\fP produces, library version, as much as possible of your code that uses libcurl, operating system name and version, compiler name and version etc. If \fICURLOPT_VERBOSE(3)\fP is not enough, you increase the level of debug data your application receive by using the \fICURLOPT_DEBUGFUNCTION(3)\fP. Getting some in\-depth knowledge about the protocols involved is never wrong, and if you are trying to do funny things, you might understand libcurl and how to use it better if you study the appropriate RFC documents at least briefly. .SH Upload Data to a Remote Site libcurl tries to keep a protocol independent approach to most transfers, thus uploading to a remote FTP site is similar to uploading data to an HTTP server with a PUT request. Of course, first you either create an easy handle or you reuse one existing one. Then you set the URL to operate on just like before. This is the remote URL, that we now upload. Since we write an application, we most likely want libcurl to get the upload data by asking us for it. To make it do that, we set the read callback and the custom pointer libcurl passes to our read callback. The read callback should have a prototype similar to: .nf size_t function(char bufptr, size_t size, size_t nitems, void userp); .fi Where \fIbufptr\fP is the pointer to a buffer we fill in with data to upload and \fInitems\fP is the size of the buffer and therefore also the maximum amount of data we can return to libcurl in this call. The \fIuserp\fP pointer is the custom pointer we set to point to a struct of ours to pass private data between the application and the callback. .nf curl_easy_setopt(handle, CURLOPT_READFUNCTION, read_function); curl_easy_setopt(handle, CURLOPT_READDATA, &filedata); .fi Tell libcurl that we want to upload: .nf curl_easy_setopt(handle, CURLOPT_UPLOAD, 1L); .fi A few protocols do not behave properly when uploads are done without any prior knowledge of the expected file size. So, set the upload file size using the \fICURLOPT_INFILESIZE_LARGE(3)\fP for all known file sizes like this[1]: .nf / in this example, file_size must be an curl_off_t variable / curl_easy_setopt(handle, CURLOPT_INFILESIZE_LARGE, file_size); .fi When you call \fIcurl_easy_perform(3)\fP this time, it performs all the necessary operations and when it has invoked the upload it calls your supplied callback to get the data to upload. The program should return as much data as possible in every invoke, as that is likely to make the upload perform as fast as possible. The callback should return the number of bytes it wrote in the buffer. Returning 0 signals the end of the upload. .SH Passwords Many protocols use or even require that username and password are provided to be able to download or upload the data of your choice. libcurl offers several ways to specify them. Most protocols support that you specify the name and password in the URL itself. libcurl detects this and use them accordingly. This is written like this: .nf protocol://user:password@example.com/path/ .fi If you need any odd letters in your username or password, you should enter them URL encoded, as %XX where XX is a two\-digit hexadecimal number. libcurl also provides options to set various passwords. The username and password as shown embedded in the URL can instead get set with the \fICURLOPT_USERPWD(3)\fP option. The argument passed to libcurl should be a char to a string in the format "user:password". In a manner like this: .nf curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); .fi Another case where name and password might be needed at times, is for those users who need to authenticate themselves to a proxy they use. libcurl offers another option for this, the \fICURLOPT_PROXYUSERPWD(3)\fP. It is used quite similar to the \fICURLOPT_USERPWD(3)\fP option like this: .nf curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); .fi There is a long time Unix "standard" way of storing FTP usernames and passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks the \fI%USERPROFILE% environment\fP variable if \fI%HOME%\fP is unset, and tries \&"_netrc" as name). The file should be made private so that only the user may read it (see also the "Security Considerations" chapter), as it might contain the password in plain text. libcurl has the ability to use this file to figure out what set of username and password to use for a particular host. As an extension to the normal functionality, libcurl also supports this file for non\-FTP protocols such as HTTP. To make curl use this file, use the \fICURLOPT_NETRC(3)\fP option: .nf curl_easy_setopt(handle, CURLOPT_NETRC, 1L); .fi A basic example of how such a .netrc file may look like: .nf machine myhost.mydomain.com login userlogin password secretword .fi All these examples have been cases where the password has been optional, or at least you could leave it out and have libcurl attempt to do its job without it. There are times when the password is not optional, like when you are using an SSL private key for secure transfers. To pass the known private key password to libcurl: .nf curl_easy_setopt(handle, CURLOPT_KEYPASSWD, "keypassword"); .fi .SH HTTP Authentication The previous chapter showed how to set username and password for getting URLs that require authentication. When using the HTTP protocol, there are many different ways a client can provide those credentials to the server and you can control which way libcurl uses them. The default HTTP authentication method is called \(aqBasic\(aq, which is sending the name and password in clear\-text in the HTTP request, base64\-encoded. This is insecure. At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, Negotiate (SPNEGO). You can tell libcurl which one to use with \fICURLOPT_HTTPAUTH(3)\fP as in: .nf curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); .fi When you send authentication to a proxy, you can also set authentication type the same way but instead with \fICURLOPT_PROXYAUTH(3)\fP: .nf curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); .fi Both these options allow you to set multiple types (by ORing them together), to make libcurl pick the most secure one out of the types the server/proxy claims to support. This method does however add a round\-trip since libcurl must first ask the server what it supports: .nf curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST\|CURLAUTH_BASIC); .fi For convenience, you can use the \fICURLAUTH_ANY\fP define (instead of a list with specific types) which allows libcurl to use whatever method it wants. When asking for multiple types, libcurl picks the available one it considers \&"best" in its own internal order of preference. .SH HTTP POSTing We get many questions regarding how to issue HTTP POSTs with libcurl the proper way. This chapter thus includes examples using both different versions of HTTP POST that libcurl supports. The first version is the simple POST, the most common version, that most HTML pages using the <form> tag uses. We provide a pointer to the data and tell libcurl to post it all to the remote site: .nf char data="name=daniel&project=curl"; curl_easy_setopt(handle, CURLOPT_POSTFIELDS, data); curl_easy_setopt(handle, CURLOPT_URL, "http://posthere.com/"); curl_easy_perform(handle); / post away! / .fi Simple enough, huh? Since you set the POST options with the \fICURLOPT_POSTFIELDS(3)\fP, this automatically switches the handle to use POST in the upcoming request. What if you want to post binary data that also requires you to set the Content\-Type: header of the post? Well, binary posts prevent libcurl from being able to do strlen() on the data to figure out the size, so therefore we must tell libcurl the size of the post data. Setting headers in libcurl requests are done in a generic way, by building a list of our own headers and then passing that list to libcurl. .nf struct curl_slist headers=NULL; headers = curl_slist_append(headers, "Content-Type: text/xml"); /* post binary data / curl_easy_setopt(handle, CURLOPT_POSTFIELDS, binaryptr); / set the size of the postfields data / curl_easy_setopt(handle, CURLOPT_POSTFIELDSIZE, 23L); / pass our list of custom made headers / curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); curl_easy_perform(handle); / post away! / curl_slist_free_all(headers); / free the header list / .fi While the simple examples above cover the majority of all cases where HTTP POST operations are required, they do not do multi\-part formposts. Multi\-part formposts were introduced as a better way to post (possibly large) binary data and were first documented in the RFC 1867 (updated in RFC 2388). They are called multi\-part because they are built by a chain of parts, each part being a single unit of data. Each part has its own name and contents. You can in fact create and post a multi\-part formpost with the regular libcurl POST support described above, but that would require that you build a formpost yourself and provide to libcurl. To make that easier, libcurl provides a MIME API consisting in several functions: using those, you can create and fill a multi\-part form. Function \fIcurl_mime_init(3)\fP creates a multi\-part body; you can then append new parts to a multi\-part body using \fIcurl_mime_addpart(3)\fP. There are three possible data sources for a part: memory using \fIcurl_mime_data(3)\fP, file using \fIcurl_mime_filedata(3)\fP and user\-defined data read callback using \fIcurl_mime_data_cb(3)\fP. \fIcurl_mime_name(3)\fP sets a part\(aqs (i.e.: form field) name, while \fIcurl_mime_filename(3)\fP fills in the remote filename. With \fIcurl_mime_type(3)\fP, you can tell the MIME type of a part, \fIcurl_mime_headers(3)\fP allows defining the part\(aqs headers. When a multi\-part body is no longer needed, you can destroy it using \fIcurl_mime_free(3)\fP. The following example sets two simple text parts with plain textual contents, and then a file with binary contents and uploads the whole thing. .nf curl_mime multipart = curl_mime_init(handle); curl_mimepart part = curl_mime_addpart(multipart); curl_mime_name(part, "name"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); part = curl_mime_addpart(multipart); curl_mime_name(part, "project"); curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); part = curl_mime_addpart(multipart); curl_mime_name(part, "logotype-image"); curl_mime_filedata(part, "curl.png"); / Set the form info / curl_easy_setopt(handle, CURLOPT_MIMEPOST, multipart); curl_easy_perform(handle); / post away! / / free the post data again / curl_mime_free(multipart); .fi To post multiple files for a single form field, you must supply each file in a separate part, all with the same field name. Although function \fIcurl_mime_subparts(3)\fP implements nested multi\-parts, this way of multiple files posting is deprecated by RFC 7578, chapter 4.3. To set the data source from an already opened FILE pointer, use: .nf curl_mime_data_cb(part, filesize, (curl_read_callback) fread, (curl_seek_callback) fseek, NULL, filepointer); .fi A deprecated \fIcurl_formadd(3)\fP function is still supported in libcurl. It should however not be used anymore for new designs and programs using it ought to be converted to the MIME API. It is however described here as an aid to conversion. Using \fIcurl_formadd\fP, you add parts to the form. When you are done adding parts, you post the whole form. The MIME API example above is expressed as follows using this function: .nf struct curl_httppost post=NULL; struct curl_httppost last=NULL; curl_formadd(&post, &last, CURLFORM_COPYNAME, "name", CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); curl_formadd(&post, &last, CURLFORM_COPYNAME, "project", CURLFORM_COPYCONTENTS, "curl", CURLFORM_END); curl_formadd(&post, &last, CURLFORM_COPYNAME, "logotype-image", CURLFORM_FILECONTENT, "curl.png", CURLFORM_END); / Set the form info / curl_easy_setopt(handle, CURLOPT_HTTPPOST, post); curl_easy_perform(handle); / post away! / / free the post data again / curl_formfree(post); .fi Multipart formposts are chains of parts using MIME\-style separators and headers. It means that each one of these separate parts get a few headers set that describe the individual content\-type, size etc. To enable your application to handicraft this formpost even more, libcurl allows you to supply your own set of custom headers to such an individual form part. You can of course supply headers to as many parts as you like, but this little example shows how you set headers to one specific part when you add that to the post handle: .nf struct curl_slist headers=NULL; headers = curl_slist_append(headers, "Content-Type: text/xml"); curl_formadd(&post, &last, CURLFORM_COPYNAME, "logotype-image", CURLFORM_FILECONTENT, "curl.xml", CURLFORM_CONTENTHEADER, headers, CURLFORM_END); curl_easy_perform(handle); /* post away! / curl_formfree(post); / free post / curl_slist_free_all(headers); / free custom header list / .fi Since all options on an easy handle are "sticky", they remain the same until changed even if you do call \fIcurl_easy_perform(3)\fP, you may need to tell curl to go back to a plain GET request if you intend to do one as your next request. You force an easy handle to go back to GET by using the \fICURLOPT_HTTPGET(3)\fP option: .nf curl_easy_setopt(handle, CURLOPT_HTTPGET, 1L); .fi Just setting \fICURLOPT_POSTFIELDS(3)\fP to "" or NULL does \fInot\fP stop libcurl from doing a POST. It just makes it POST without any data to send! .SH Converting from deprecated form API to MIME API Four rules have to be respected in building the multi\-part: - The easy handle must be created before building the multi\-part. - The multi\-part is always created by a call to curl_mime_init(handle). - Each part is created by a call to curl_mime_addpart(multipart). - When complete, the multi\-part must be bound to the easy handle using \fICURLOPT_MIMEPOST(3)\fP instead of \fICURLOPT_HTTPPOST(3)\fP. Here are some example of \fIcurl_formadd\fP calls to MIME API sequences: .nf curl_formadd(&post, &last, CURLFORM_COPYNAME, "id", CURLFORM_COPYCONTENTS, "daniel", CURLFORM_END); CURLFORM_CONTENTHEADER, headers, CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "id"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); curl_mime_headers(part, headers, FALSE); .fi Setting the last \fIcurl_mime_headers(3)\fP argument to TRUE would have caused the headers to be automatically released upon destroyed the multi\-part, thus saving a clean\-up call to \fIcurl_slist_free_all(3)\fP. .nf curl_formadd(&post, &last, CURLFORM_PTRNAME, "logotype-image", CURLFORM_FILECONTENT, "-", CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "logotype-image"); curl_mime_data_cb(part, (curl_off_t) -1, fread, fseek, NULL, stdin); .fi \fIcurl_mime_name(3)\fP always copies the field name. The special filename "\-" is not supported by \fIcurl_mime_filename(3)\fP: to read an open file, use a callback source using fread(). The transfer is be chunk\-encoded since the data size is unknown. .nf curl_formadd(&post, &last, CURLFORM_COPYNAME, "datafile[]", CURLFORM_FILE, "file1", CURLFORM_FILE, "file2", CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "datafile[]"); curl_mime_filedata(part, "file1"); part = curl_mime_addpart(multipart); curl_mime_name(part, "datafile[]"); curl_mime_filedata(part, "file2"); .fi The deprecated multipart/mixed implementation of multiple files field is translated to two distinct parts with the same name. .nf curl_easy_setopt(handle, CURLOPT_READFUNCTION, myreadfunc); curl_formadd(&post, &last, CURLFORM_COPYNAME, "stream", CURLFORM_STREAM, arg, CURLFORM_CONTENTLEN, (curl_off_t) datasize, CURLFORM_FILENAME, "archive.zip", CURLFORM_CONTENTTYPE, "application/zip", CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "stream"); curl_mime_data_cb(part, (curl_off_t) datasize, myreadfunc, NULL, NULL, arg); curl_mime_filename(part, "archive.zip"); curl_mime_type(part, "application/zip"); .fi \fICURLOPT_READFUNCTION(3)\fP callback is not used: it is replace by directly setting the part source data from the callback read function. .nf curl_formadd(&post, &last, CURLFORM_COPYNAME, "memfile", CURLFORM_BUFFER, "memfile.bin", CURLFORM_BUFFERPTR, databuffer, CURLFORM_BUFFERLENGTH, (long) sizeof databuffer, CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "memfile"); curl_mime_data(part, databuffer, (curl_off_t) sizeof databuffer); curl_mime_filename(part, "memfile.bin"); .fi \fIcurl_mime_data(3)\fP always copies the initial data: data buffer is thus free for immediate reuse. .nf curl_formadd(&post, &last, CURLFORM_COPYNAME, "message", CURLFORM_FILECONTENT, "msg.txt", CURLFORM_END); .fi becomes: .nf part = curl_mime_addpart(multipart); curl_mime_name(part, "message"); curl_mime_filedata(part, "msg.txt"); curl_mime_filename(part, NULL); .fi Use of \fIcurl_mime_filedata(3)\fP sets the remote filename as a side effect: it is therefore necessary to clear it for \fICURLFORM_FILECONTENT\fP emulation. .SH Showing Progress For historical and traditional reasons, libcurl has a built\-in progress meter that can be switched on and then makes it present a progress meter in your terminal. Switch on the progress meter by, oddly enough, setting \fICURLOPT_NOPROGRESS(3)\fP to zero. This option is set to 1 by default. For most applications however, the built\-in progress meter is useless and what instead is interesting is the ability to specify a progress callback. The function pointer you pass to libcurl is then called on irregular intervals with information about the current transfer. Set the progress callback by using \fICURLOPT_PROGRESSFUNCTION(3)\fP. Pass a pointer to a function that matches this prototype: .nf int progress_callback(void clientp, double dltotal, double dlnow, double ultotal, double ulnow); .fi If any of the input arguments is unknown, a 0 is provided. The first argument, the \(aqclientp\(aq is the pointer you pass to libcurl with \fICURLOPT_PROGRESSDATA(3)\fP. libcurl does not touch it. .SH libcurl with C++ There is basically only one thing to keep in mind when using C++ instead of C when interfacing libcurl: The callbacks CANNOT be non\-static class member functions Example C++ code: .nf class AClass { static size_t write_data(void ptr, size_t size, size_t nmemb, void ourpointer) { /* do what you want with the data / } } .fi .SH Proxies What "proxy" means according to Merriam\-Webster: "a person authorized to act for another" but also "the agency, function, or office of a deputy who acts as a substitute for another". Proxies are exceedingly common these days. Companies often only offer Internet access to employees through their proxies. Network clients or user\-agents ask the proxy for documents, the proxy does the actual request and then it returns them. libcurl supports SOCKS and HTTP proxies. When a given URL is wanted, libcurl asks the proxy for it instead of trying to connect to the actual remote host identified in the URL. If you are using a SOCKS proxy, you may find that libcurl does not quite support all operations through it. For HTTP proxies: the fact that the proxy is an HTTP proxy puts certain restrictions on what can actually happen. A requested URL that might not be a HTTP URL is passed to the HTTP proxy to deliver back to libcurl. This happens transparently, and an application may not need to know. I say "may", because at times it is important to understand that all operations over an HTTP proxy use the HTTP protocol. For example, you cannot invoke your own custom FTP commands or even proper FTP directory listings. .IP "Proxy Options" To tell libcurl to use a proxy at a given port number: .nf curl_easy_setopt(handle, CURLOPT_PROXY, "proxy-host.com:8080"); .fi Some proxies require user authentication before allowing a request, and you pass that information similar to this: .nf curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "user:password"); .fi If you want to, you can specify the hostname only in the \fICURLOPT_PROXY(3)\fP option, and set the port number separately with \fICURLOPT_PROXYPORT(3)\fP. Tell libcurl what kind of proxy it is with \fICURLOPT_PROXYTYPE(3)\fP (if not, it defaults to assuming an HTTP proxy): .nf curl_easy_setopt(handle, CURLOPT_PROXYTYPE, CURLPROXY_SOCKS4); .fi .IP "Environment Variables" libcurl automatically checks and uses a set of environment variables to know what proxies to use for certain protocols. The names of the variables are following an old tradition and are built up as "[protocol]_proxy" (note the lower casing). Which makes the variable \(aqhttp_proxy\(aq checked for a name of a proxy to use when the input URL is HTTP. Following the same rule, the variable named \(aqftp_proxy\(aq is checked for FTP URLs. Again, the proxies are always HTTP proxies, the different names of the variables simply allows different HTTP proxies to be used. The proxy environment variable contents should be in the format \&"[protocol://][user:password@]machine[:port]". Where the protocol:// part specifies which type of proxy it is, and the optional port number specifies on which port the proxy operates. If not specified, the internal default port number is used and that is most likely not the one you would like it to be. There are two special environment variables. \(aqall_proxy\(aq is what sets proxy for any URL in case the protocol specific variable was not set, and \(aqno_proxy\(aq defines a list of hosts that should not use a proxy even though a variable may say so. If \(aqno_proxy\(aq is a plain asterisk ("") it matches all hosts. To explicitly disable libcurl\(aqs checking for and using the proxy environment variables, set the proxy name to "" \- an empty string \- with \fICURLOPT_PROXY(3)\fP. .IP "SSL and Proxies" SSL is for secure point\-to\-point connections. This involves strong encryption and similar things, which effectively makes it impossible for a proxy to operate as a "man in between" which the proxy\(aqs task is, as previously discussed. Instead, the only way to have SSL work over an HTTP proxy is to ask the proxy to tunnel everything through without being able to check or fiddle with the traffic. Opening an SSL connection over an HTTP proxy is therefore a matter of asking the proxy for a straight connection to the target host on a specified port. This is made with the HTTP request CONNECT. ("please dear proxy, connect me to that remote host"). Because of the nature of this operation, where the proxy has no idea what kind of data that is passed in and out through this tunnel, this breaks some of the few advantages that come from using a proxy, such as caching. Many organizations prevent this kind of tunneling to other destination port numbers than 443 (which is the default HTTPS port number). .IP "Tunneling Through Proxy" As explained above, tunneling is required for SSL to work and often even restricted to the operation intended for SSL; HTTPS. This is however not the only time proxy\-tunneling might offer benefits to you or your application. As tunneling opens a direct connection from your application to the remote machine, it suddenly also re\-introduces the ability to do non\-HTTP operations over an HTTP proxy. You can in fact use things such as FTP upload or FTP custom commands this way. Again, this is often prevented by the administrators of proxies and is rarely allowed. Tell libcurl to use proxy tunneling like this: .nf curl_easy_setopt(handle, CURLOPT_HTTPPROXYTUNNEL, 1L); .fi In fact, there might even be times when you want to do plain HTTP operations using a tunnel like this, as it then enables you to operate on the remote server instead of asking the proxy to do so. libcurl does not stand in the way for such innovative actions either! .IP "Proxy Auto-Config" Netscape first came up with this. It is basically a webpage (usually using a \&.pac extension) with a JavaScript that when executed by the browser with the requested URL as input, returns information to the browser on how to connect to the URL. The returned information might be "DIRECT" (which means no proxy should be used), "PROXY host:port" (to tell the browser where the proxy for this particular URL is) or "SOCKS host:port" (to direct the browser to a SOCKS proxy). libcurl has no means to interpret or evaluate JavaScript and thus it does not support this. If you get yourself in a position where you face this nasty invention, the following advice have been mentioned and used in the past: - Depending on the JavaScript complexity, write up a script that translates it to another language and execute that. - Read the JavaScript code and rewrite the same logic in another language. - Implement a JavaScript interpreter; people have successfully used the Mozilla JavaScript engine in the past. - Ask your admins to stop this, for a static proxy setup or similar. .SH Persistence Is The Way to Happiness Re\-cycling the same easy handle several times when doing multiple requests is the way to go. After each single \fIcurl_easy_perform(3)\fP operation, libcurl keeps the connection alive and open. A subsequent request using the same easy handle to the same host might just be able to use the already open connection! This reduces network impact a lot. Even if the connection is dropped, all connections involving SSL to the same host again, benefit from libcurl\(aqs session ID cache that drastically reduces re\-connection time. FTP connections that are kept alive save a lot of time, as the command\- response round\-trips are skipped, and also you do not risk getting blocked without permission to login again like on many FTP servers only allowing N persons to be logged in at the same time. libcurl caches DNS name resolving results, to make lookups of a previously looked up name a lot faster. Other interesting details that improve performance for subsequent requests may also be added in the future. Each easy handle attempts to keep the last few connections alive for a while in case they are to be used again. You can set the size of this "cache" with the \fICURLOPT_MAXCONNECTS(3)\fP option. Default is 5. There is rarely any point in changing this value, and if you think of changing this it is often just a matter of thinking again. To force your upcoming request to not use an already existing connection, you can do that by setting \fICURLOPT_FRESH_CONNECT(3)\fP to 1. In a similar spirit, you can also forbid the upcoming request to be "lying" around and possibly get reused after the request by setting \fICURLOPT_FORBID_REUSE(3)\fP to 1. .SH HTTP Headers Used by libcurl When you use libcurl to do HTTP requests, it passes along a series of headers automatically. It might be good for you to know and understand these. You can replace or remove them by using the \fICURLOPT_HTTPHEADER(3)\fP option. .IP Host This header is required by HTTP 1.1 and even many 1.0 servers and should be the name of the server we want to talk to. This includes the port number if anything but default. .IP Accept \&"\fI/\fP" .IP Expect When doing POST requests, libcurl sets this header to "100\-continue" to ask the server for an "OK" message before it proceeds with sending the data part of the post. If the posted data amount is deemed "small", libcurl does not use this header. .SH Customizing Operations There is an ongoing development today where more and more protocols are built upon HTTP for transport. This has obvious benefits as HTTP is a tested and reliable protocol that is widely deployed and has excellent proxy\-support. When you use one of these protocols, and even when doing other kinds of programming you may need to change the traditional HTTP (or FTP or...) manners. You may need to change words, headers or various data. libcurl is your friend here too. .IP CURLOPT_CUSTOMREQUEST If just changing the actual HTTP request keyword is what you want, like when GET, HEAD or POST is not good enough for you, \fICURLOPT_CUSTOMREQUEST(3)\fP is there for you. It is simple to use: .nf curl_easy_setopt(handle, CURLOPT_CUSTOMREQUEST, "MYOWNREQUEST"); .fi When using the custom request, you change the request keyword of the actual request you are performing. Thus, by default you make a GET request but you can also make a POST operation (as described before) and then replace the POST keyword if you want to. You are the boss. .IP "Modify Headers" HTTP\-like protocols pass a series of headers to the server when doing the request, and you are free to pass any amount of extra headers that you think fit. Adding headers is this easy: .nf struct curl_slist headers=NULL; / init to NULL is important / headers = curl_slist_append(headers, "Hey-server-hey: how are you?"); headers = curl_slist_append(headers, "X-silly-content: yes"); / pass our list of custom made headers / curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); curl_easy_perform(handle); / transfer http / curl_slist_free_all(headers); / free the header list / .fi \&... and if you think some of the internally generated headers, such as Accept: or Host: do not contain the data you want them to contain, you can replace them by simply setting them too: .nf headers = curl_slist_append(headers, "Accept: Agent-007"); headers = curl_slist_append(headers, "Host: munged.host.line"); .fi .IP "Delete Headers" If you replace an existing header with one with no contents, you prevent the header from being sent. For instance, if you want to completely prevent the \&"Accept:" header from being sent, you can disable it with code similar to this: headers = curl_slist_append(headers, "Accept:"); Both replacing and canceling internal headers should be done with careful consideration and you should be aware that you may violate the HTTP protocol when doing so. .IP "Enforcing chunked transfer-encoding" By making sure a request uses the custom header "Transfer\-Encoding: chunked" when doing a non\-GET HTTP operation, libcurl switches over to "chunked" upload, even though the size of the data to upload might be known. By default, libcurl usually switches over to chunked upload automatically if the upload data size is unknown. .IP "HTTP Version" All HTTP requests includes the version number to tell the server which version we support. libcurl speaks HTTP 1.1 by default. Some old servers do not like getting 1.1\-requests and when dealing with stubborn old things like that, you can tell libcurl to use 1.0 instead by doing something like this: curl_easy_setopt(handle, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_0); .IP "FTP Custom Commands" Not all protocols are HTTP\-like, and thus the above may not help you when you want to make, for example, your FTP transfers to behave differently. Sending custom commands to an FTP server means that you need to send the commands exactly as the FTP server expects them (RFC 959 is a good guide here), and you can only use commands that work on the control\-connection alone. All kinds of commands that require data interchange and thus need a data\-connection must be left to libcurl\(aqs own judgment. Also be aware that libcurl does its best to change directory to the target directory before doing any transfer, so if you change directory (with CWD or similar) you might confuse libcurl and then it might not attempt to transfer the file in the correct remote directory. A little example that deletes a given file before an operation: .nf headers = curl_slist_append(headers, "DELE file-to-remove"); / pass the list of custom commands to the handle / curl_easy_setopt(handle, CURLOPT_QUOTE, headers); curl_easy_perform(handle); / transfer ftp data! / curl_slist_free_all(headers); / free the header list / .fi If you would instead want this operation (or chain of operations) to happen _after_ the data transfer took place the option to \fIcurl_easy_setopt(3)\fP would instead be called \fICURLOPT_POSTQUOTE(3)\fP and used the exact same way. The custom FTP commands are issued to the server in the same order they are added to the list, and if a command gets an error code returned back from the server, no more commands are issued and libcurl bails out with an error code (CURLE_QUOTE_ERROR). Note that if you use \fICURLOPT_QUOTE(3)\fP to send commands before a transfer, no transfer actually takes place when a quote command has failed. If you set the \fICURLOPT_HEADER(3)\fP to 1, you tell libcurl to get information about the target file and output "headers" about it. The headers are in "HTTP\-style", looking like they do in HTTP. The option to enable headers or to run custom FTP commands may be useful to combine with \fICURLOPT_NOBODY(3)\fP. If this option is set, no actual file content transfer is performed. .IP "FTP Custom CURLOPT_CUSTOMREQUEST" If you do want to list the contents of an FTP directory using your own defined FTP command, \fICURLOPT_CUSTOMREQUEST(3)\fP does just that. "NLST" is the default one for listing directories but you are free to pass in your idea of a good alternative. .SH Cookies Without Chocolate Chips In the HTTP sense, a cookie is a name with an associated value. A server sends the name and value to the client, and expects it to get sent back on every subsequent request to the server that matches the particular conditions set. The conditions include that the domain name and path match and that the cookie has not become too old. In real\-world cases, servers send new cookies to replace existing ones to update them. Server use cookies to "track" users and to keep "sessions". Cookies are sent from server to clients with the header Set\-Cookie: and they are sent from clients to servers with the Cookie: header. To just send whatever cookie you want to a server, you can use \fICURLOPT_COOKIE(3)\fP to set a cookie string like this: .nf curl_easy_setopt(handle, CURLOPT_COOKIE, "name1=var1; name2=var2;"); .fi In many cases, that is not enough. You might want to dynamically save whatever cookies the remote server passes to you, and make sure those cookies are then used accordingly on later requests. One way to do this, is to save all headers you receive in a plain file and when you make a request, you tell libcurl to read the previous headers to figure out which cookies to use. Set the header file to read cookies from with \fICURLOPT_COOKIEFILE(3)\fP. The \fICURLOPT_COOKIEFILE(3)\fP option also automatically enables the cookie parser in libcurl. Until the cookie parser is enabled, libcurl does not parse or understand incoming cookies and they are just be ignored. However, when the parser is enabled the cookies are understood and the cookies are kept in memory and used properly in subsequent requests when the same handle is used. Many times this is enough, and you may not have to save the cookies to disk at all. Note that the file you specify to \fICURLOPT_COOKIEFILE(3)\fP does not have to exist to enable the parser, so a common way to just enable the parser and not read any cookies is to use the name of a file you know does not exist. If you would rather use existing cookies that you have previously received with your Netscape or Mozilla browsers, you can make libcurl use that cookie file as input. The \fICURLOPT_COOKIEFILE(3)\fP is used for that too, as libcurl automatically finds out what kind of file it is and acts accordingly. Perhaps the most advanced cookie operation libcurl offers, is saving the entire internal cookie state back into a Netscape/Mozilla formatted cookie file. We call that the cookie\-jar. When you set a filename with \fICURLOPT_COOKIEJAR(3)\fP, that filename is created and all received cookies get stored in it when \fIcurl_easy_cleanup(3)\fP is called. This enables cookies to get passed on properly between multiple handles without any information getting lost. .SH FTP Peculiarities We Need FTP transfers use a second TCP/IP connection for the data transfer. This is usually a fact you can forget and ignore but at times this detail comes back to haunt you. libcurl offers several different ways to customize how the second connection is being made. libcurl can either connect to the server a second time or tell the server to connect back to it. The first option is the default and it is also what works best for all the people behind firewalls, NATs or IP\-masquerading setups. libcurl then tells the server to open up a new port and wait for a second connection. This is by default attempted with EPSV first, and if that does not work it tries PASV instead. (EPSV is an extension to the original FTP spec and does not exist nor work on all FTP servers.) You can prevent libcurl from first trying the EPSV command by setting \fICURLOPT_FTP_USE_EPSV(3)\fP to zero. In some cases, you want to have the server connect back to you for the second connection. This might be when the server is perhaps behind a firewall or something and only allows connections on a single port. libcurl then informs the remote server which IP address and port number to connect to. This is made with the \fICURLOPT_FTPPORT(3)\fP option. If you set it to "\-", libcurl uses your system\(aqs "default IP address". If you want to use a particular IP, you can set the full IP address, a hostname to resolve to an IP address or even a local network interface name that libcurl gets the IP address from. When doing the "PORT" approach, libcurl attempts to use the EPRT and the LPRT before trying PORT, as they work with more protocols. You can disable this behavior by setting \fICURLOPT_FTP_USE_EPRT(3)\fP to zero. .SH MIME API revisited for SMTP and IMAP In addition to support HTTP multi\-part form fields, the MIME API can be used to build structured email messages and send them via SMTP or append such messages to IMAP directories. A structured email message may contain several parts: some are displayed inline by the MUA, some are attachments. Parts can also be structured as multi\-part, for example to include another email message or to offer several text formats alternatives. This can be nested to any level. To build such a message, you prepare the nth\-level multi\-part and then include it as a source to the parent multi\-part using function \fIcurl_mime_subparts(3)\fP. Once it has been bound to its parent multi\-part, a nth\-level multi\-part belongs to it and should not be freed explicitly. Email messages data is not supposed to be non\-ASCII and line length is limited: fortunately, some transfer encodings are defined by the standards to support the transmission of such incompatible data. Function \fIcurl_mime_encoder(3)\fP tells a part that its source data must be encoded before being sent. It also generates the corresponding header for that part. If the part data you want to send is already encoded in such a scheme, do not use this function (this would over\-encode it), but explicitly set the corresponding part header. Upon sending such a message, libcurl prepends it with the header list set with \fICURLOPT_HTTPHEADER(3)\fP, as zero level mime part headers. Here is an example building an email message with an inline plain/html text alternative and a file attachment encoded in base64: .nf curl_mime message = curl_mime_init(handle); /* The inline part is an alternative proposing the html and the text versions of the email. / curl_mime alt = curl_mime_init(handle); /* HTML message. / curl_mimepart part = curl_mime_addpart(alt); curl_mime_data(part, "<html><body><p>This is HTML</p></body></html>", CURL_ZERO_TERMINATED); curl_mime_type(part, "text/html"); /* Text message. / part = curl_mime_addpart(alt); curl_mime_data(part, "This is plain text message", CURL_ZERO_TERMINATED); / Create the inline part. / part = curl_mime_addpart(message); curl_mime_subparts(part, alt); curl_mime_type(part, "multipart/alternative"); struct curl_slist headers = curl_slist_append(NULL, "Content-Disposition: inline"); curl_mime_headers(part, headers, TRUE); /* Add the attachment. / part = curl_mime_addpart(message); curl_mime_filedata(part, "manual.pdf"); curl_mime_encoder(part, "base64"); / Build the mail headers. / headers = curl_slist_append(NULL, "From: me@example.com"); headers = curl_slist_append(headers, "To: you@example.com"); / Set these into the easy handle. */ curl_easy_setopt(handle, CURLOPT_HTTPHEADER, headers); curl_easy_setopt(handle, CURLOPT_MIMEPOST, mime); .fi It should be noted that appending a message to an IMAP directory requires the message size to be known prior upload. It is therefore not possible to include parts with unknown data size in this context. .SH Headers Equal Fun Some protocols provide "headers", meta\-data separated from the normal data. These headers are by default not included in the normal data stream, but you can make them appear in the data stream by setting \fICURLOPT_HEADER(3)\fP to 1. What might be even more useful, is libcurl\(aqs ability to separate the headers from the data and thus make the callbacks differ. You can for example set a different pointer to pass to the ordinary write callback by setting \fICURLOPT_HEADERDATA(3)\fP. Or, you can set an entirely separate function to receive the headers, by using \fICURLOPT_HEADERFUNCTION(3)\fP. The headers are passed to the callback function one by one, and you can depend on that fact. It makes it easier for you to add custom header parsers etc. \&"Headers" for FTP transfers equal all the FTP server responses. They are not actually true headers, but in this case we pretend they are! ;\-) .SH Post Transfer Information See \fIcurl_easy_getinfo(3)\fP. .SH The multi Interface The easy interface as described in detail in this document is a synchronous interface that transfers one file at a time and does not return until it is done. The multi interface, on the other hand, allows your program to transfer multiple files in both directions at the same time, without forcing you to use multiple threads. The name might make it seem that the multi interface is for multi\-threaded programs, but the truth is almost the reverse. The multi interface allows a single\-threaded application to perform the same kinds of multiple, simultaneous transfers that multi\-threaded programs can perform. It allows many of the benefits of multi\-threaded transfers without the complexity of managing and synchronizing many threads. To complicate matters somewhat more, there are even two versions of the multi interface. The event based one, also called multi_socket and the "normal one" designed for using with select(). See the libcurl\-multi.3 man page for details on the multi_socket event based API, this description here is for the select() oriented one. To use this interface, you are better off if you first understand the basics of how to use the easy interface. The multi interface is simply a way to make multiple transfers at the same time by adding up multiple easy handles into a "multi stack". You create the easy handles you want, one for each concurrent transfer, and you set all the options just like you learned above, and then you create a multi handle with \fIcurl_multi_init(3)\fP and add all those easy handles to that multi handle with \fIcurl_multi_add_handle(3)\fP. When you have added the handles you have for the moment (you can still add new ones at any time), you start the transfers by calling \fIcurl_multi_perform(3)\fP. \fIcurl_multi_perform(3)\fP is asynchronous. It only performs what can be done now and then return control to your program. It is designed to never block. You need to keep calling the function until all transfers are completed. The best usage of this interface is when you do a select() on all possible file descriptors or sockets to know when to call libcurl again. This also makes it easy for you to wait and respond to actions on your own application\(aqs sockets/handles. You figure out what to select() for by using \fIcurl_multi_fdset(3)\fP, that fills in a set of \fIfd_set\fP variables for you with the particular file descriptors libcurl uses for the moment. When you then call select(), it returns when one of the file handles signal action and you then call \fIcurl_multi_perform(3)\fP to allow libcurl to do what it wants to do. Take note that libcurl does also feature some time\-out code so we advise you to never use long timeouts on select() before you call \fIcurl_multi_perform(3)\fP again. \fIcurl_multi_timeout(3)\fP is provided to help you get a suitable timeout period. Another precaution you should use: always call \fIcurl_multi_fdset(3)\fP immediately before the select() call since the current set of file descriptors may change in any curl function invoke. If you want to stop the transfer of one of the easy handles in the stack, you can use \fIcurl_multi_remove_handle(3)\fP to remove individual easy handles. Remember that easy handles should be \fIcurl_easy_cleanup(3)\fPed. When a transfer within the multi stack has finished, the counter of running transfers (as filled in by \fIcurl_multi_perform(3)\fP) decreases. When the number reaches zero, all transfers are done. \fIcurl_multi_info_read(3)\fP can be used to get information about completed transfers. It then returns the CURLcode for each easy transfer, to allow you to figure out success on each individual transfer. .SH SSL, Certificates and Other Tricks [ seeding, passwords, keys, certificates, ENGINE, ca certs ] .SH Sharing Data Between Easy Handles You can share some data between easy handles when the easy interface is used, and some data is share automatically when you use the multi interface. When you add easy handles to a multi handle, these easy handles automatically share a lot of the data that otherwise would be kept on a per\-easy handle basis when the easy interface is used. The DNS cache is shared between handles within a multi handle, making subsequent name resolving faster, and the connection pool that is kept to better allow persistent connections and connection reuse is also shared. If you are using the easy interface, you can still share these between specific easy handles by using the share interface, see \fIlibcurl\-share(3)\fP. Some things are never shared automatically, not within multi handles, like for example cookies so the only way to share that is with the share interface. .SH Footnotes .IP [1] libcurl 7.10.3 and later have the ability to switch over to chunked Transfer\-Encoding in cases where HTTP uploads are done with data of an unknown size. .IP [2] This happens on Windows machines when libcurl is built and used as a DLL. However, you can still do this on Windows if you link with a static library. .IP [3] The curl\-config tool is generated at build\-time (on Unix\-like systems) and should be installed with the \(aqmake install\(aq or similar instruction that installs the library, header files, man pages etc. .IP [4] This behavior was different in versions before 7.17.0, where strings had to remain valid past the end of the \fIcurl_easy_setopt(3)\fP call. .SH SEE ALSO .BR libcurl-easy (3), .BR libcurl-errors (3), .BR libcurl-multi (3), .BR libcurl-url (3)	59.42 KB	2025-07-08 09:41
📄 libcurl-url.3 .\" generated by cd2nroff 0.1 from libcurl-url.md .TH libcurl-url 3 "2025-06-27" libcurl .SH NAME libcurl\-url \- URL interface overview .SH DESCRIPTION The URL interface provides functions for parsing and generating URLs. .SH INCLUDE You still only include <curl/curl.h> in your code. .SH CREATE Create a handle that holds URL info and resources with \fIcurl_url(3)\fP: .nf CURLU h = curl_url(); .fi .SH CLEANUP When done with it, clean it up with \fIcurl_url_cleanup(3)\fP .nf curl_url_cleanup(h); .fi .SH DUPLICATE When you need a copy of a handle, just duplicate it with \fIcurl_url_dup(3)\fP: .nf CURLU nh = curl_url_dup(h); .fi .SH PARSING By setting a URL to the handle with \fIcurl_url_set(3)\fP, the URL is parsed and stored in the handle. If the URL is not syntactically correct it returns an error instead. .nf rc = curl_url_set(h, CURLUPART_URL, "https://example.com:449/foo/bar?name=moo", 0); .fi The zero in the fourth argument is a bitmask for changing specific features. If successful, this stores the URL in its individual parts within the handle. .SH REDIRECT When a handle already contains info about a URL, setting a relative URL makes it "redirect" to that. .nf rc = curl_url_set(h, CURLUPART_URL, "../test?another", 0); .fi .SH GET URL The \fBCURLU\fP handle represents a URL and you can easily extract that with \fIcurl_url_get(3)\fP: .nf char *url; rc = curl_url_get(h, CURLUPART_URL, &url, 0); curl_free(url); .fi The zero in the fourth argument is a bitmask for changing specific features. .SH GET PARTS When a URL has been parsed or parts have been set, you can extract those pieces from the handle at any time. .nf rc = curl_url_get(h, CURLUPART_FRAGMENT, &fragment, 0); rc = curl_url_get(h, CURLUPART_HOST, &host, 0); rc = curl_url_get(h, CURLUPART_PASSWORD, &password, 0); rc = curl_url_get(h, CURLUPART_PATH, &path, 0); rc = curl_url_get(h, CURLUPART_PORT, &port, 0); rc = curl_url_get(h, CURLUPART_QUERY, &query, 0); rc = curl_url_get(h, CURLUPART_SCHEME, &scheme, 0); rc = curl_url_get(h, CURLUPART_USER, &user, 0); rc = curl_url_get(h, CURLUPART_ZONEID, &zoneid, 0); .fi Extracted parts are not URL decoded unless the user also asks for it with the \fICURLU_URLDECODE\fP flag set in the fourth bitmask argument. Remember to free the returned string with \fIcurl_free(3)\fP when you are done with it. .SH SET PARTS A user set individual URL parts, either after having parsed a full URL or instead of parsing such. .nf rc = curl_url_set(urlp, CURLUPART_FRAGMENT, "anchor", 0); rc = curl_url_set(urlp, CURLUPART_HOST, "www.example.com", 0); rc = curl_url_set(urlp, CURLUPART_PASSWORD, "doe", 0); rc = curl_url_set(urlp, CURLUPART_PATH, "/index.html", 0); rc = curl_url_set(urlp, CURLUPART_PORT, "443", 0); rc = curl_url_set(urlp, CURLUPART_QUERY, "name=john", 0); rc = curl_url_set(urlp, CURLUPART_SCHEME, "https", 0); rc = curl_url_set(urlp, CURLUPART_USER, "john", 0); rc = curl_url_set(urlp, CURLUPART_ZONEID, "eth0", 0); .fi Set parts are not URL encoded unless the user asks for it with the \fICURLU_URLENCODE\fP flag. .SH CURLU_APPENDQUERY An application can append a string to the right end of the query part with the \fICURLU_APPENDQUERY\fP flag to \fIcurl_url_set(3)\fP. Imagine a handle that holds the URL "https://example.com/?shoes=2". An application can then add the string "hat=1" to the query part like this: .nf rc = curl_url_set(urlp, CURLUPART_QUERY, "hat=1", CURLU_APPENDQUERY); .fi It notices the lack of an ampersand (&) separator and injects one, and the handle\(aqs full URL then equals "https://example.com/?shoes=2&hat=1". The appended string can of course also get URL encoded on add, and if asked to URL encode, the encoding process skips the \(aq=\(aq character. For example, append \&"candy=N&N" to what we already have, and URL encode it to deal with the ampersand in the data: .nf rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", CURLU_APPENDQUERY \| CURLU_URLENCODE); .fi Now the URL looks like .nf https://example.com/?shoes=2&hat=1&candy=N%26N .fi .SH NOTES A URL with a literal IPv6 address can be parsed even when IPv6 support is not enabled. .SH SEE ALSO .BR CURLOPT_URL (3), .BR curl_url (3), .BR curl_url_cleanup (3), .BR curl_url_dup (3), .BR curl_url_get (3), .BR curl_url_set (3), .BR curl_url_strerror (3)	4.29 KB	2025-07-08 09:41
📄 libcurl-ws.3 .\" generated by cd2nroff 0.1 from libcurl-ws.md .TH libcurl-ws 3 "2025-06-27" libcurl .SH NAME libcurl\-ws \- WebSocket interface overview .SH DESCRIPTION The WebSocket interface provides functions for receiving and sending WebSocket data. .SH INCLUDE You still only include <curl/curl.h> in your code. .SH SETUP WebSocket is also often known as \fIWebSockets\fP, in plural. It is done by upgrading a regular HTTP(S) GET request to a WebSocket connection. WebSocket is a TCP\-like message\-based communication protocol done over HTTP, specified in RFC 6455. To initiate a WebSocket session with libcurl, setup an easy handle to use a URL with a "WS://" or "WSS://" scheme. "WS" is for cleartext communication over HTTP and "WSS" is for doing WebSocket securely over HTTPS. A WebSocket request is done as an HTTP/1 GET request with an "Upgrade WebSocket" request header field. When the upgrade is accepted by the server, it responds with a 101 Switching and then the client can speak WebSocket with the server. The communication can happen in both directions at the same time. .SH EXTENSIONS The WebSocket protocol allows the client to request and negotiate \fIextensions\fP can add additional features and restrictions to the protocol. libcurl does not support the use of extensions and always sets up a connection without them. .SH MESSAGES WebSocket communication is message based. That means that both ends send and receive entire messages, not streams like TCP. A WebSocket message is sent over the wire in one or more frames. A message which is split into several frames is referred to as a \fIfragmented\fP message and the individual frames are called \fIfragments\fP. Each frame (or fragment) in a message can have a size of up to 2^63 bytes and declares the frame size in the header. The total size of a message that is fragmented into multiple frames is not limited by the protocol and the number of fragments is not known until the final fragment is received. Transmission of a frame must not be interrupted by any other data transfers and transmission of the different fragments of a message must not be interrupted by other user data frames. Control frames \- PING, PONG and CLOSE \- may be transmitted in between any other two frames, even in between two fragments of the same user data message. The control frames themselves on the other hand must never be fragmented and are limited to a size of 125 bytes. libcurl delivers WebSocket data as chunks of frames. It might deliver a whole frame as a single chunk, but it might also deliver it in several pieces depending on size and network patterns. See the individual API documentations for further information. .SH PING WebSocket is designed to allow long\-lived sessions and in order to keep the connections alive, both ends can send PING messages for the other end to respond with a PONG. Both ends may also send unsolicited PONG messages as unidirectional heartbeat. libcurl automatically responds to server PING messages with a PONG that echoes the payload of the PING message. libcurl does neither send any PING messages nor any unsolicited PONG messages automatically. The automatic reply to PING messages can be disabled through \fICURLOPT_WS_OPTIONS(3)\fP. .SH MODELS Because of the many different ways WebSocket can be used, which is much more flexible than limited to plain downloads or uploads, libcurl offers two different API models to use it: 1. CURLOPT_WRITEFUNCTION model: Using a write callback with \fICURLOPT_WRITEFUNCTION(3)\fP much like other downloads for when the traffic is download oriented. 2. CURLOPT_CONNECT_ONLY model: Using \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP functions. .IP "CURLOPT_WRITEFUNCTION MODEL" \fICURLOPT_CONNECT_ONLY(3)\fP must be unset or \fB0L\fP for this model to take effect. \fIcurl_easy_perform(3)\fP establishes and sets up the WebSocket communication and then blocks for the whole duration of the connection. libcurl calls the callback configured in \fICURLOPT_WRITEFUNCTION(3)\fP, whenever an incoming chunk of WebSocket data is received. The callback is handed a pointer to the payload data as an argument and can call \fIcurl_ws_meta(3)\fP to get relevant metadata. .IP "CURLOPT_CONNECT_ONLY MODEL" \fICURLOPT_CONNECT_ONLY(3)\fP must be \fB2L\fP for this model to take effect. \fIcurl_easy_perform(3)\fP only establishes and sets up the WebSocket communication and then returns control back to the application. The application can then use \fIcurl_ws_recv(3)\fP and \fIcurl_ws_send(3)\fP to exchange WebSocket messages with the server. .SH RAW MODE libcurl can be told to speak WebSocket in "raw mode" by setting the \fBCURLWS_RAW_MODE\fP bit of the \fICURLOPT_WS_OPTIONS(3)\fP option. Raw WebSocket means that libcurl passes on the data from the network without parsing it, leaving that entirely to the application. This mode is intended for applications that already have a WebSocket parser/engine and want to switch over to use libcurl for enabling WebSocket, and keep parts of the existing software architecture. .SH SEE ALSO .BR CURLOPT_CONNECT_ONLY (3), .BR CURLOPT_WRITEFUNCTION (3), .BR CURLOPT_WS_OPTIONS (3), .BR curl_easy_init (3), .BR curl_ws_meta (3), .BR curl_ws_recv (3), .BR curl_ws_send (3)	5.13 KB	2025-07-08 09:41
📄 libcurl.3 .\" generated by cd2nroff 0.1 from libcurl.md .TH libcurl 3 "2025-06-27" libcurl .SH NAME libcurl \- client\-side URL transfers .SH DESCRIPTION This is a short overview on how to use libcurl in your C programs. There are specific man pages for each function mentioned in here. See \fIlibcurl\-easy(3)\fP, \fIlibcurl\-multi(3)\fP, \fIlibcurl\-share(3)\fP, \fIlibcurl\-url(3)\fP, \fIlibcurl\-ws(3)\fP and \fIlibcurl\-tutorial(3)\fP for in\-depth understanding on how to program with libcurl. There are many bindings available that bring libcurl access to your favorite language. Look elsewhere for documentation on those. .SH TRANSFERS To transfer files, you create an "easy handle" using \fIcurl_easy_init(3)\fP for a single individual transfer (in either direction). You then set your desired set of options in that handle with \fIcurl_easy_setopt(3)\fP. Options you set with \fIcurl_easy_setopt(3)\fP stick. They are then used for every repeated use of this handle until you either change the option, or you reset them all with \fIcurl_easy_reset(3)\fP. To actually transfer data you have the option of using the "easy" interface, or the "multi" interface. The easy interface is a synchronous interface with which you call \fIcurl_easy_perform(3)\fP and let it perform the transfer. When it is completed, the function returns and you can continue. More details are found in the \fIlibcurl\-easy(3)\fP man page. The multi interface on the other hand is an asynchronous interface, that you call and that performs only a little piece of the transfer on each invoke. It is perfect if you want to do things while the transfer is in progress, or similar. The multi interface allows you to select() on libcurl action, and even to easily download multiple files simultaneously using a single thread. See further details in the \fIlibcurl\-multi(3)\fP man page. .SH SUPPORT INTERFACES There is also a series of other helpful functions and interface families to use, including these: .IP curl_version_info() gets detailed libcurl (and other used libraries) version info. See \fIcurl_version_info(3)\fP .IP curl_getdate() converts a date string to time_t. See \fIcurl_getdate(3)\fP .IP curl_easy_getinfo() get information about a performed transfer. See \fIcurl_easy_getinfo(3)\fP .IP curl_mime_addpart() helps building an HTTP form POST. See \fIcurl_mime_addpart(3)\fP .IP curl_slist_append() builds a linked list. See \fIcurl_slist_append(3)\fP .IP "Sharing data between transfers" You can have multiple easy handles share certain data, even if they are used in different threads. This magic is setup using the share interface, as described in the \fIlibcurl\-share(3)\fP man page. .IP "URL Parsing" URL parsing and manipulations. See \fIlibcurl\-url(3)\fP .IP "WebSocket communication" See \fIlibcurl\-ws(3)\fP .SH LINKING WITH LIBCURL On Unix\-like machines, there is a tool named curl\-config that gets installed with the rest of the curl stuff when \(aqmake install\(aq is performed. curl\-config is added to make it easier for applications to link with libcurl and developers to learn about libcurl and how to use it. Run \(aqcurl\-config \--libs\(aq to get the (additional) linker options you need to link with the particular version of libcurl you have installed. See the \fIcurl\-config(1)\fP man page for further details. Unix\-like operating system that ship libcurl as part of their distributions often do not provide the curl\-config tool, but simply install the library and headers in the common path for this purpose. Many Linux and similar systems use pkg\-config to provide build and link options about libraries and libcurl supports that as well. .SH LIBCURL SYMBOL NAMES All public functions in the libcurl interface are prefixed with \(aqcurl_\(aq (with a lowercase c). You can find other functions in the library source code, but other prefixes indicate that the functions are private and may change without further notice in the next release. Only use documented functions and functionality. .SH PORTABILITY libcurl works \fBexactly\fP the same, on any of the platforms it compiles and builds on. .SH THREADS libcurl is thread safe but there are a few exceptions. Refer to \fIlibcurl\-thread(3)\fP for more information. .SH PERSISTENT CONNECTIONS Persistent connections means that libcurl can reuse the same connection for several transfers, if the conditions are right. libcurl always attempts to use persistent connections. Whenever you use \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP etc, libcurl attempts to use an existing connection to do the transfer, and if none exists it opens a new one that is subject for reuse on a possible following call to \fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP. To allow libcurl to take full advantage of persistent connections, you should do as many of your file transfers as possible using the same handle. If you use the easy interface, and you call \fIcurl_easy_cleanup(3)\fP, all the possibly open connections held by libcurl are closed and forgotten. When you have created a multi handle and are using the multi interface, the connection pool is instead kept in the multi handle so closing and creating new easy handles to do transfers do not affect them. Instead all added easy handles can take advantage of the single shared pool. .SH GLOBAL CONSTANTS There are a variety of constants that libcurl uses, mainly through its internal use of other libraries, which are too complicated for the library loader to set up. Therefore, a program must call a library function after the program is loaded and running to finish setting up the library code. For example, when libcurl is built for SSL capability via the GNU TLS library, there is an elaborate tree inside that library that describes the SSL protocol. \fIcurl_global_init(3)\fP is the function that you must call. This may allocate resources (e.g. the memory for the GNU TLS tree mentioned above), so the companion function \fIcurl_global_cleanup(3)\fP releases them. If libcurl was compiled with support for multiple SSL backends, the function \fIcurl_global_sslset(3)\fP can be called before \fIcurl_global_init(3)\fP to select the active SSL backend. The global constant functions are thread\-safe since libcurl 7.84.0 if \fIcurl_version_info(3)\fP has the CURL_VERSION_THREADSAFE feature bit set (most platforms). Read \fIlibcurl\-thread(3)\fP for thread safety guidelines. If the global constant functions are \fInot thread safe\fP, then you must not call them when any other thread in the program is running. It is not good enough that no other thread is using libcurl at the time, because these functions internally call similar functions of other libraries, and those functions are similarly thread\-unsafe. You cannot generally know what these libraries are, or whether other threads are using them. If the global constant functions are \fInot thread safe\fP, then the basic rule for constructing a program that uses libcurl is this: Call \fIcurl_global_init(3)\fP, with a \fICURL_GLOBAL_ALL\fP argument, immediately after the program starts, while it is still only one thread and before it uses libcurl at all. Call \fIcurl_global_cleanup(3)\fP immediately before the program exits, when the program is again only one thread and after its last use of libcurl. It is not actually required that the functions be called at the beginning and end of the program \-- that is just usually the easiest way to do it. You can call both of these multiple times, as long as all calls meet these requirements and the number of calls to each is the same. The global constant situation merits special consideration when the code you are writing to use libcurl is not the main program, but rather a modular piece of a program, e.g. another library. As a module, your code does not know about other parts of the program \-- it does not know whether they use libcurl or not. Its code does not necessarily run at the start and end of the whole program. A module like this must have global constant functions of its own, just like \fIcurl_global_init(3)\fP and \fIcurl_global_cleanup(3)\fP. The module thus has control at the beginning and end of the program and has a place to call the libcurl functions. If multiple modules in the program use libcurl, they all separately call the libcurl functions, and that is OK because only the first \fIcurl_global_init(3)\fP and the last \fIcurl_global_cleanup(3)\fP in a program change anything. (libcurl uses a reference count in static memory). In a C++ module, it is common to deal with the global constant situation by defining a special class that represents the global constant environment of the module. A program always has exactly one object of the class, in static storage. That way, the program automatically calls the constructor of the object as the program starts up and the destructor as it terminates. As the author of this libcurl\-using module, you can make the constructor call \fIcurl_global_init(3)\fP and the destructor call \fIcurl_global_cleanup(3)\fP and satisfy libcurl\(aqs requirements without your user having to think about it. (Caveat: If you are initializing libcurl from a Windows DLL you should not initialize it from \fIDllMain\fP or a static initializer because Windows holds the loader lock during that time and it could cause a deadlock.) \fIcurl_global_init(3)\fP has an argument that tells what particular parts of the global constant environment to set up. In order to successfully use any value except \fICURL_GLOBAL_ALL\fP (which says to set up the whole thing), you must have specific knowledge of internal workings of libcurl and all other parts of the program of which it is part. A special part of the global constant environment is the identity of the memory allocator. \fIcurl_global_init(3)\fP selects the system default memory allocator, but you can use \fIcurl_global_init_mem(3)\fP to supply one of your own. However, there is no way to use \fIcurl_global_init_mem(3)\fP in a modular program \-- all modules in the program that might use libcurl would have to agree on one allocator. There is a failsafe in libcurl that makes it usable in simple situations without you having to worry about the global constant environment at all: \fIcurl_easy_init(3)\fP sets up the environment itself if it has not been done yet. The resources it acquires to do so get released by the operating system automatically when the program exits. This failsafe feature exists mainly for backward compatibility because there was a time when the global functions did not exist. Because it is sufficient only in the simplest of programs, it is not recommended for any program to rely on it. .SH SEE ALSO .BR libcurl-easy (3), .BR libcurl-multi (3), .BR libcurl-security (3), .BR libcurl-thread (3)	10.57 KB	2025-07-08 09:41

Edit File:

Terminal