diff options
| author | Seonah Moon <seonah1.moon@samsung.com> | 2022-01-12 13:27:51 +0900 |
|---|---|---|
| committer | Seonah Moon <seonah1.moon@samsung.com> | 2022-01-12 13:28:56 +0900 |
| commit | 58f7e70ff869dee66c90b1323e0d5c9f324067b8 (patch) | |
| tree | 31060230fe108ac26a3258e1b4fb22454c7cf01c /docs/libcurl/opts | |
| parent | b31894b8fe11ff4cfe97bd63eb4e62e14893c749 (diff) | |
| download | curl-58f7e70ff869dee66c90b1323e0d5c9f324067b8.tar.gz curl-58f7e70ff869dee66c90b1323e0d5c9f324067b8.tar.bz2 curl-58f7e70ff869dee66c90b1323e0d5c9f324067b8.zip | |
Imported Upstream version 7.81.0upstream/7.81.0
Change-Id: Ibe8b1de1691e326fbd2a8133470758ab942cbd97
Diffstat (limited to 'docs/libcurl/opts')
388 files changed, 4603 insertions, 1927 deletions
diff --git a/docs/libcurl/opts/CMakeLists.txt b/docs/libcurl/opts/CMakeLists.txt index 98acedf2a..d0035016d 100644 --- a/docs/libcurl/opts/CMakeLists.txt +++ b/docs/libcurl/opts/CMakeLists.txt @@ -9,7 +9,7 @@ # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms -# are also available at https://curl.haxx.se/docs/copyright.html. +# are also available at https://curl.se/docs/copyright.html. # # You may opt to use, copy, modify, merge, publish, distribute and/or sell # copies of the Software, and permit persons to whom the Software is diff --git a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 index bd38d48c3..484582657 100644 --- a/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 +++ b/docs/libcurl/opts/CURLINFO_ACTIVESOCKET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_ACTIVESOCKET 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_ACTIVESOCKET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 @@ -40,7 +42,7 @@ 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 isn't working on all platforms. +\fICURLINFO_LASTSOCKET(3)\fP since that one is not working on all platforms. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 index bd50055b6..f7c03f4f0 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,23 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_APPCONNECT_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_APPCONNECT_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 very near to the \fICURLINFO_PRETRANSFER_TIME(3)\fP -time, except for cases such as HTTP pipelining where the pretransfer time can -be delayed due to waits in line for the pipeline and more. +This time is most often close to the \fICURLINFO_PRETRANSFER_TIME(3)\fP time, +except for cases such as HTTP pipelining where the pretransfer time can be +delayed due to waits in line for the pipeline and more. When a redirect is followed, the time from each request is added together. diff --git a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 index 498053a54..af1a3109a 100644 --- a/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_APPCONNECT_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_APPCONNECT_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_APPCONNECT_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .SH NAME CURLINFO_APPCONNECT_TIME_T \- 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_T, curl_off_t *timep); +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 very near to the \fICURLINFO_PRETRANSFER_TIME_T(3)\fP -time, except for cases such as HTTP pipelining where the pretransfer time can -be delayed due to waits in line for the pipeline and more. +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 +pipelining where the pretransfer time can be delayed due to waits in line for +the pipeline and more. When a redirect is followed, the time from each request is added together. diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.3 b/docs/libcurl/opts/CURLINFO_CERTINFO.3 index f7be3209f..a0c075acc 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.3 +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CERTINFO 3 "July 04, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CERTINFO 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 'struct curl_certinfo *' and you'll get it set to point to +Pass a pointer to a 'struct curl_certinfo *' and you will get it set to point to a struct that holds a number of linked lists with info about the certificate chain, assuming you had \fICURLOPT_CERTINFO(3)\fP enabled when the request was made. The struct reports how many certs it found and then you can extract info @@ -72,8 +74,9 @@ if(curl) { } .fi .SH AVAILABILITY -This option is only working in libcurl built with OpenSSL, NSS, Schannel or -GSKit support. Schannel support added in 7.50.0 +This option is only working in libcurl built with OpenSSL, NSS, Schannel, GSKit +or Secure Transport support. Schannel support added in 7.50.0. Secure Transport +support added in 7.79.0. Added in 7.19.1 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 index 98d72d10c..01dbf39f7 100644 --- a/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 +++ b/docs/libcurl/opts/CURLINFO_CONDITION_UNMET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONDITION_UNMET 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONDITION_UNMET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 didn't match (see \fICURLOPT_TIMECONDITION(3)\fP). Alas, -if this returns a 1 you know that the reason you didn't get data in return is -because it didn't fulfill the condition. The long this argument points to will +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 will get 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. diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 index bee7a2fa0..a746300d3 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONNECT_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONNECT_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 index a924573c3..266334277 100644 --- a/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_CONNECT_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONNECT_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONNECT_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. +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. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 index d01f10750..cc70a940c 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 isn't known. +-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. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 index 65647284f..9a6cd8c8d 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_DOWNLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONTENT_LENGTH_DOWNLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 isn't known. +the size is not known. .SH PROTOCOLS HTTP(S) .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 index ab45f583c..3d875cc1d 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONTENT_LENGTH_UPLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 isn't known. +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. diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 index e562e805a..c5261f70b 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_LENGTH_UPLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONTENT_LENGTH_UPLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 isn't known. +upload. Stores -1 if the size is not known. .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 index 6a739d6ee..33b58f335 100644 --- a/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 +++ b/docs/libcurl/opts/CURLINFO_CONTENT_TYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_CONTENT_TYPE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_CONTENT_TYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 didn't send a valid Content-Type header or that the -protocol used doesn't support this. +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 will be NULL or pointing to private memory you MUST NOT free it - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the diff --git a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 b/docs/libcurl/opts/CURLINFO_COOKIELIST.3 index 4ce9ba31a..57cc85d12 100644 --- a/docs/libcurl/opts/CURLINFO_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLINFO_COOKIELIST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_COOKIELIST 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_COOKIELIST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 'struct curl_slist *' to receive a linked-list of all -cookies curl knows (expired ones, too). Don't forget to call +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) 'struct curl_slist *' will be set to point to NULL. @@ -62,7 +64,7 @@ if(curl) { printf("%s\\n", each->data); each = each->next; } - /* we must free these cookies when we're done */ + /* we must free these cookies when we are done */ curl_slist_free_all(cookies); } } diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 index 36cf62149..0287eca9d 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_METHOD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_EFFECTIVE_METHOD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_EFFECTIVE_METHOD 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .SH NAME CURLINFO_EFFECTIVE_METHOD \- get the last used HTTP method @@ -35,8 +35,8 @@ CURLcode curl_easy_getinfo(CURL *handle, CURLINFO_EFFECTIVE_METHOD, Pass in a pointer to a char pointer and get the last used effective HTTP method. -In cases when you've asked libcurl to follow redirects, the method may very -well not be the same method the first request would use. +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 will be NULL or pointing to private memory you MUST NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the diff --git a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 index a3066efff..deee3180b 100644 --- a/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 +++ b/docs/libcurl/opts/CURLINFO_EFFECTIVE_URL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_EFFECTIVE_URL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_EFFECTIVE_URL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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've asked libcurl to follow redirects, it may very well not -be the same value you set with \fICURLOPT_URL(3)\fP. +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 will be NULL or pointing to private memory you MUST NOT free - it gets freed when you call \fIcurl_easy_cleanup(3)\fP on the diff --git a/docs/libcurl/opts/CURLINFO_FILETIME.3 b/docs/libcurl/opts/CURLINFO_FILETIME.3 index 04185bbad..db59e383c 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_FILETIME 3 "January 25, 2018" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_FILETIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 1 jan 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 doesn't support the command that tells document time +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 tell libcurl to collect this information before the transfer is made, diff --git a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 index 4d3556a69..60639dbe3 100644 --- a/docs/libcurl/opts/CURLINFO_FILETIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_FILETIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_FILETIME 3 "January 25, 2018" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_FILETIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 1 jan 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 doesn't support the command that tells document +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, diff --git a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 index c38dc5464..aae1bc409 100644 --- a/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 +++ b/docs/libcurl/opts/CURLINFO_FTP_ENTRY_PATH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_FTP_ENTRY_PATH 3 "May 06, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_FTP_ENTRY_PATH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 index 71aa2d9cf..c8ad987e3 100644 --- a/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 +++ b/docs/libcurl/opts/CURLINFO_HEADER_SIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_HEADER_SIZE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_HEADER_SIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 index 0dadef431..80b1f46ad 100644 --- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 +++ b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_HTTPAUTH_AVAIL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_HTTPAUTH_AVAIL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 index 68e2b9854..c45c76e4b 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 +++ b/docs/libcurl/opts/CURLINFO_HTTP_CONNECTCODE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_HTTP_CONNECTCODE 3 "May 06, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_HTTP_CONNECTCODE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 will be zero if no such response code diff --git a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 index 8600f64a3..986b1b075 100644 --- a/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLINFO_HTTP_VERSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_HTTP_VERSION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_HTTP_VERSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. The returned value will be CURL_HTTP_VERSION_1_0, CURL_HTTP_VERSION_1_1, CURL_HTTP_VERSION_2_0, CURL_HTTP_VERSION_3 or 0 if the -version can't be determined. +version cannot be determined. .SH PROTOCOLS HTTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 b/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 index 9e436a10e..fc1e81f50 100644 --- a/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 +++ b/docs/libcurl/opts/CURLINFO_LASTSOCKET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_LASTSOCKET 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_LASTSOCKET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. @@ -47,7 +49,7 @@ All .nf CURL *curl = curl_easy_init(); if(curl) { - long sockfd; /* doesn't work on win64! */ + 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 */ diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 b/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 index f336c40ef..cf0eca004 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 +++ b/docs/libcurl/opts/CURLINFO_LOCAL_IP.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_LOCAL_IP 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_LOCAL_IP 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 index 5e690c763..38d21bb63 100644 --- a/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 +++ b/docs/libcurl/opts/CURLINFO_LOCAL_PORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2015, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_LOCAL_PORT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_LOCAL_PORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 index 40e936edd..f4c16ac27 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_NAMELOOKUP_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_NAMELOOKUP_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 index 833991a87..e29f6b0b5 100644 --- a/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_NAMELOOKUP_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_NAMELOOKUP_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_NAMELOOKUP_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 index 96f7d5f21..f06fa6925 100644 --- a/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 +++ b/docs/libcurl/opts/CURLINFO_NUM_CONNECTS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_NUM_CONNECTS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_NUM_CONNECTS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 b/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 index ef58727f7..263b36851 100644 --- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 +++ b/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_OS_ERRNO 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_OS_ERRNO 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 index 97f7d4366..9e0595018 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PRETRANSFER_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PRETRANSFER_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 includes all -pre-transfer commands and negotiations that are specific to the particular -protocol(s) involved. It does \fInot\fP involve the sending of the protocol- -specific request that triggers a transfer. +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 protocol instructions that triggers a transfer. When a redirect is followed, the time from each request is added together. diff --git a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 index ecbd4f48e..ffb72bff8 100644 --- a/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_PRETRANSFER_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PRETRANSFER_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PRETRANSFER_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 index f78097b7d..70201870b 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_IP.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2015, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PRIMARY_IP 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PRIMARY_IP 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 index 622cb990f..41fa43d7c 100644 --- a/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 +++ b/docs/libcurl/opts/CURLINFO_PRIMARY_PORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PRIMARY_PORT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PRIMARY_PORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_PRIVATE.3 b/docs/libcurl/opts/CURLINFO_PRIVATE.3 index 337392242..1b9e9cbbf 100644 --- a/docs/libcurl/opts/CURLINFO_PRIVATE.3 +++ b/docs/libcurl/opts/CURLINFO_PRIVATE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PRIVATE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PRIVATE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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). diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 index cecf67986..8b845fd91 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PROTOCOL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PROTOCOL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 Pass a pointer to a long to receive the version used in the last http connection. The returned value will be exactly one of the CURLPROTO_* values: diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 index 5b8da3dac..577070472 100644 --- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 +++ b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PROXYAUTH_AVAIL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PROXYAUTH_AVAIL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 index 5d95a4366..b0cddfed6 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 +++ b/docs/libcurl/opts/CURLINFO_PROXY_ERROR.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PROXY_ERROR 3 "August 24, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PROXY_ERROR 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_getinfo options" .SH NAME CURLINFO_PROXY_ERROR \- get the detailed (SOCKS) proxy error diff --git a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 index c48e6ba00..af02c325b 100644 --- a/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 +++ b/docs/libcurl/opts/CURLINFO_PROXY_SSL_VERIFYRESULT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_PROXY_SSL_VERIFYRESULT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 index bf88f4494..443f271ac 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_COUNT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_REDIRECT_COUNT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_REDIRECT_COUNT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 index 5748f169b..c1cc4b3d3 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_REDIRECT_TIME 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_REDIRECT_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 index ca87a6f55..1609fc246 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_REDIRECT_TIME_T 3 "May 17, 2018" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_REDIRECT_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 index 8d3f91792..e3a1c0322 100644 --- a/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 +++ b/docs/libcurl/opts/CURLINFO_REDIRECT_URL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_REDIRECT_URL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_REDIRECT_URL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 -very handy if you think using the built-in libcurl redirect logic isn't good -enough for you but you would still prefer to avoid implementing all the magic -of figuring out the new URL. +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). diff --git a/docs/libcurl/opts/CURLINFO_REFERER.3 b/docs/libcurl/opts/CURLINFO_REFERER.3 new file mode 100644 index 000000000..618efba0a --- /dev/null +++ b/docs/libcurl/opts/CURLINFO_REFERER.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLINFO_REFERER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" + +.SH NAME +CURLINFO_REFERER \- get the referrer 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. + +The \fBhdrp\fP pointer will be NULL or pointing 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 +HTTP(S) +.SH EXAMPLE +.nf +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 7.76.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR curl_easy_getinfo "(3), " curl_easy_setopt "(3), " +.BR CURLOPT_REFERER "(3), " diff --git a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 index af83f1e42..6a684fd19 100644 --- a/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 +++ b/docs/libcurl/opts/CURLINFO_REQUEST_SIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_REQUEST_SIZE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_REQUEST_SIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 index 649f9d66f..a2c93805b 100644 --- a/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 +++ b/docs/libcurl/opts/CURLINFO_RESPONSE_CODE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,24 +20,25 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RESPONSE_CODE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RESPONSE_CODE 3 "December 14, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 or SMTP -response code. This option was previously known as CURLINFO_HTTP_CODE in -libcurl 7.10.7 and earlier. The stored value will be zero if no server -response code has been received. Note that a proxy's CONNECT response should +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 will be zero if no server response code has been received. +Note that a proxy's CONNECT response should be read with \fICURLINFO_HTTP_CONNECTCODE(3)\fP and not this. - -Support for SMTP responses added in 7.25.0. .SH PROTOCOLS -HTTP, FTP and SMTP +HTTP, FTP, SMTP and LDAP .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -54,6 +55,7 @@ if(curl) { .fi .SH AVAILABILITY Added in 7.10.8. 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 RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 index 8ad9e56ad..0c1c8f6d2 100644 --- a/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 +++ b/docs/libcurl/opts/CURLINFO_RETRY_AFTER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RETRY_AFTER 3 "October 03, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RETRY_AFTER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 @@ -35,7 +38,7 @@ issued. The information from the "Retry-After:" header. While the HTTP header might contain a fixed date string, the \fICURLINFO_RETRY_AFTER(3)\fP will always return number of seconds to wait - -or zero if there was no header or the header couldn't be parsed. +or zero if there was no header or the header could not be parsed. .SH DEFAULT Returns zero delay if there was no header. .SH PROTOCOLS @@ -57,7 +60,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in curl 7.66.0 +Added in 7.66.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 index 4dfe53d09..897ddb331 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_CLIENT_CSEQ.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RTSP_CLIENT_CSEQ 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RTSP_CLIENT_CSEQ 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 will be used by the application. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 index 33edf441f..3d9b8d470 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_CSEQ_RECV.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RTSP_CSEQ_RECV 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RTSP_CSEQ_RECV 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 index dd3f0ded4..8cc2c5853 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_SERVER_CSEQ.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RTSP_SERVER_CSEQ 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RTSP_SERVER_CSEQ 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 will be expected by the application. diff --git a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 index 246720961..f936baf26 100644 --- a/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 +++ b/docs/libcurl/opts/CURLINFO_RTSP_SESSION_ID.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_RTSP_SESSION_ID 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_RTSP_SESSION_ID 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_SCHEME.3 b/docs/libcurl/opts/CURLINFO_SCHEME.3 index ed101540d..2e1f89e74 100644 --- a/docs/libcurl/opts/CURLINFO_SCHEME.3 +++ b/docs/libcurl/opts/CURLINFO_SCHEME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SCHEME 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SCHEME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 index db5763a4f..93146e3b7 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SIZE_DOWNLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SIZE_DOWNLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 will be reset diff --git a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 index 8efd0a8e5..3ef36d5d4 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_DOWNLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SIZE_DOWNLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SIZE_DOWNLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 will be reset diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 index 3f2bd192e..abf05107f 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SIZE_UPLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SIZE_UPLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 index bc639ddb4..71cea8fb6 100644 --- a/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SIZE_UPLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SIZE_UPLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SIZE_UPLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 index e8a78d5db..2879d1886 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SPEED_DOWNLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SPEED_DOWNLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 index 9a9f66a19..c23b08451 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SPEED_DOWNLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SPEED_DOWNLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SPEED_DOWNLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 index fccc1cec8..faf68272c 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SPEED_UPLOAD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SPEED_UPLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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. diff --git a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 index 759049784..9aacdb1bd 100644 --- a/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 +++ b/docs/libcurl/opts/CURLINFO_SPEED_UPLOAD_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SPEED_UPLOAD_T 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SPEED_UPLOAD_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 index 6cccb93e9..c230df7d3 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 +++ b/docs/libcurl/opts/CURLINFO_SSL_ENGINES.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,23 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SSL_ENGINES 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SSL_ENGINES 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 'struct curl_slist *' 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 run-time. \fBNOTE:\fP you must call \fIcurl_slist_free_all(3)\fP -on the list pointer once you're done with it, as libcurl will not free the +on the list pointer once you are done with it, as libcurl will not free the data for you. .SH PROTOCOLS All TLS based ones. diff --git a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 index 2ab59be62..5da877d06 100644 --- a/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 +++ b/docs/libcurl/opts/CURLINFO_SSL_VERIFYRESULT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_SSL_VERIFYRESULT 3 "May 02, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_SSL_VERIFYRESULT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 index e0407fd2b..380689e7a 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_STARTTRANSFER_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_STARTTRANSFER_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 index 972ebe3f8..6f6e6ea93 100644 --- a/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_STARTTRANSFER_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_STARTTRANSFER_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_STARTTRANSFER_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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 diff --git a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 index 05c88e147..67ef0ce6d 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 +++ b/docs/libcurl/opts/CURLINFO_TLS_SESSION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_TLS_SESSION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_TLS_SESSION 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_getinfo options" .SH NAME CURLINFO_TLS_SESSION \- get TLS session info diff --git a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 index a74e519e8..153216d37 100644 --- a/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 +++ b/docs/libcurl/opts/CURLINFO_TLS_SSL_PTR.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_TLS_SSL_PTR 3 "August 07, 2020" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_TLS_SSL_PTR 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .SH NAME CURLINFO_TLS_SESSION, CURLINFO_TLS_SSL_PTR \- get TLS session info @@ -117,7 +117,7 @@ pointer, with the (possibly) changed certificate information. If you are using OpenSSL or wolfSSL then \fICURLOPT_SSL_CTX_FUNCTION(3)\fP can be used to set a certificate verification callback in the CTX. That is safer -than using this option to poll for certificate changes and doesn't suffer from +than using this option to poll for certificate changes and does not suffer from any of the problems above. There is currently no way in libcurl to set a verification callback for the other SSL backends. diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 index 13f84ee30..3c870846b 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_TOTAL_TIME 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_TOTAL_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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 diff --git a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 index a96148c1d..34ad3453e 100644 --- a/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 +++ b/docs/libcurl/opts/CURLINFO_TOTAL_TIME_T.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLINFO_TOTAL_TIME_T 3 "August 26, 2019" "libcurl 7.73.0" "curl_easy_getinfo options" +.TH CURLINFO_TOTAL_TIME_T 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_getinfo options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 index 6971263b3..4b3da35a1 100644 --- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "April 05, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 index c2728ea2c..cb55ad500 100644 --- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 +++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "April 05, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 index 6420cff9b..61a9674ea 100644 --- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_MAXCONNECTS 3 "March 23, 2020" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_MAXCONNECTS 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME -CURLMOPT_MAXCONNECTS \- set size of connection cache +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 set number will be used as the maximum amount of simultaneously open connections that libcurl may keep in its diff --git a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 index 99cd86c36..b1fab1426 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_CONCURRENT_STREAMS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,9 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "06 Nov 2019" "libcurl 7.67.0" "curl_multi_setopt options" +.TH CURLMOPT_MAX_CONCURRENT_STREAMS 3 "September 08, 2021" "libcurl 7.81.0" "curl_multi_setopt options" + .SH NAME -CURLMOPT_MAX_CONCURRENT_STREAMS \- set max concurrent streams for http2 +CURLMOPT_MAX_CONCURRENT_STREAMS \- max concurrent streams for http2 .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 index d825dc8d6..e1561ed59 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "May 27, 2017" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_MAX_HOST_CONNECTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME -CURLMOPT_MAX_HOST_CONNECTIONS \- set max number of connections to a single host +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); +CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_MAX_HOST_CONNECTIONS, + long max); +.fi .SH DESCRIPTION Pass a long to indicate \fBmax\fP. The set number will be used as the maximum amount of simultaneously open connections to a single host (a host being the @@ -45,6 +48,15 @@ pipeline on it. 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 will be queued up waiting for their chance. When +that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted +inclusive of the waiting time, meaning that if you set a too narrow timeout in +such a case the transfer might never even start before it times out. + +Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP +timeout is however treated as a per-connect timeout. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 index dc97a650c..7c1cb1a57 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "April 05, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_MAX_PIPELINE_LENGTH 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 index a616bdb32..da8c36175 100644 --- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 +++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "May 27, 2017" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_MAX_TOTAL_CONNECTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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 will be used as the maximum number of simultaneously open connections in total using this multi @@ -35,7 +38,16 @@ handle. For each new session, libcurl will open a new connection up to the limit set by \fICURLMOPT_MAX_TOTAL_CONNECTIONS(3)\fP. When the limit is reached, the sessions will be pending until there are available connections. If \fICURLMOPT_PIPELINING(3)\fP is enabled, libcurl will try to -pipeline or use multiplexing if the host is capable of it. +use 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 will be queued up waiting for their chance. When +that happens, the \fICURLOPT_TIMEOUT_MS(3)\fP timeout will be counted +inclusive of the waiting time, meaning that if you set a too narrow timeout in +such a case the transfer might never even start before it times out. + +Even in the queued up situation, the \fICURLOPT_CONNECTTIMEOUT_MS(3)\fP +timeout is however treated as a per-connect timeout. .SH DEFAULT The default value is 0, which means that there is no limit. It is then simply controlled by the number of easy handles added. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 index d8f1475fa..bb22d7e6b 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_PIPELINING 3 "April 05, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_PIPELINING 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_PIPELINING \- enable HTTP pipelining and multiplexing .SH SYNOPSIS +.nf #include <curl/curl.h> CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_PIPELINING, long bitmask); +.fi .SH DESCRIPTION Pass in the \fBbitmask\fP parameter to instruct libcurl to enable HTTP pipelining and/or HTTP/2 multiplexing for this multi handle. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 index 898235955..777a061c6 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SERVER_BL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_PIPELINING_SERVER_BL 3 "June 09, 2020" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_PIPELINING_SERVER_BL 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 index 1cc3da3e4..ee48a4fe6 100644 --- a/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 +++ b/docs/libcurl/opts/CURLMOPT_PIPELINING_SITE_BL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_PIPELINING_SITE_BL 3 "June 09, 2020" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_PIPELINING_SITE_BL 3 "November 26, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 index 50d9291b2..dfee356e1 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_PUSHDATA 3 "May 27, 2017" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_PUSHDATA 3 "November 04, 2020" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_PUSHDATA \- pointer to pass to push callback diff --git a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 index ca4681309..4de8591b8 100644 --- a/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_PUSHFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_PUSHFUNCTION 3 "July 16, 2020" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_PUSHFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_PUSHFUNCTION \- callback that approves or denies server pushes @@ -76,7 +76,7 @@ Returns the header at index 'num' (or NULL). The returned pointer points to a "name:value" string that will be freed when this callback returns. .IP curl_pushheader_byname Returns the value for the given header name (or NULL). This is a shortcut so -that the application doesn't have to loop through all headers to find the one +that the application does not have to loop through all headers to find the one it is interested in. The data pointed will be freed when this callback returns. If more than one header field use the same name, this returns only the first one. @@ -89,7 +89,7 @@ The callback denies the stream and no data for this will reach the application, the easy handle will be destroyed by libcurl. .IP "CURL_PUSH_ERROROUT (2)" Returning this will reject the pushed stream and return an error back on the -parent stream making it get closed with an error. (Added in curl 7.72.0) +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 diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 index e547e9e33..f595b889f 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_SOCKETDATA.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_SOCKETDATA 3 "May 31, 2017" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_SOCKETDATA 3 "November 04, 2020" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_SOCKETDATA \- custom pointer passed to the socket callback diff --git a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 index 5cfcad95d..75df846c6 100644 --- a/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_SOCKETFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_SOCKETFUNCTION 3 "June 24, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_SOCKETFUNCTION 3 "December 02, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_SOCKETFUNCTION \- callback informed about what to wait for @@ -54,6 +54,10 @@ 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 will be aborted and fail. + \fBuserp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. \fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL. diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 index 72d232624..cd81e03d5 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 +++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_TIMERDATA 3 "May 27, 2017" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_TIMERDATA 3 "November 04, 2020" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME CURLMOPT_TIMERDATA \- custom pointer to pass to timer callback diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 index 4498c2460..77f2f4870 100644 --- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 +++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLMOPT_TIMERFUNCTION 3 "May 03, 2019" "libcurl 7.73.0" "curl_multi_setopt options" +.TH CURLMOPT_TIMERFUNCTION 3 "December 02, 2021" "libcurl 7.81.0" "curl_multi_setopt options" .SH NAME -CURLMOPT_TIMERFUNCTION \- set callback to receive timeout values +CURLMOPT_TIMERFUNCTION \- callback to receive timeout values .SH SYNOPSIS .nf #include <curl/curl.h> @@ -41,9 +41,9 @@ 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 non-repeating -timer with an interval of \fBtimeout_ms\fP. When time that timer fires, call -either \fIcurl_multi_socket_action(3)\fP or \fIcurl_multi_perform(3)\fP, -depending on which interface you use. +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. 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. @@ -53,8 +53,12 @@ changed. The \fBuserp\fP pointer is set with \fICURLMOPT_TIMERDATA(3)\fP. -The timer callback should return 0 on success, and -1 on error. This callback -can be used instead of, or in addition to, \fIcurl_multi_timeout(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 will be aborted and fail. + +This callback can be used instead of, or in addition to, +\fIcurl_multi_timeout(3)\fP. \fBWARNING:\fP even if it feels tempting, avoid calling libcurl directly from within the callback itself when the \fBtimeout_ms\fP value is zero, since it diff --git a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 index 85ddd2b1e..8893fba85 100644 --- a/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 +++ b/docs/libcurl/opts/CURLOPT_ABSTRACT_UNIX_SOCKET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,39 +20,43 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ABSTRACT_UNIX_SOCKET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_ABSTRACT_UNIX_SOCKET \- set an abstract Unix domain socket +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); +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 will be 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). - -On non-supporting platforms, the abstract address will be interpreted as an empty -string and fail gracefully, generating a run-time error. +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 will be 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). -This option shares the same semantics as -.BR CURLOPT_UNIX_SOCKET_PATH "(3) -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. +On non-supporting platforms, the abstract address will be interpreted as an +empty string and fail gracefully, generating a run-time 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 Default is NULL. +.SH PROTOCOLS +All .SH EXAMPLE .nf - curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); - curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/"); + curl_easy_setopt(curl_handle, CURLOPT_ABSTRACT_UNIX_SOCKET, "/tmp/foo.sock"); + curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/"); .fi .SH AVAILABILITY -Since 7.53.0. +Added in 7.53.0. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 index bb436fec8..8af37cc07 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_ACCEPTTIMEOUT_MS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ACCEPTTIMEOUT_MS 3 "March 06, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ACCEPTTIMEOUT_MS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. diff --git a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 index 0e2d3708e..1ebdbd61d 100644 --- a/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,16 +20,18 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ACCEPT_ENCODING 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ACCEPT_ENCODING 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_ACCEPT_ENCODING \- enables automatic decompression of HTTP downloads +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 * argument specifying what encoding you'd like. +Pass a char * 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. @@ -95,7 +97,7 @@ if(curl) { .SH AVAILABILITY This option was called CURLOPT_ENCODING before 7.21.6 -The specific libcurl you're using must have been built with zlib to be able to +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. diff --git a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 index 13de8f0ba..4309d35b8 100644 --- a/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 +++ b/docs/libcurl/opts/CURLOPT_ADDRESS_SCOPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ADDRESS_SCOPE 3 "March 07, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ADDRESS_SCOPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_ADDRESS_SCOPE \- set scope id for IPv6 addresses +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 diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC.3 b/docs/libcurl/opts/CURLOPT_ALTSVC.3 index f229e8bf4..2f66b05c8 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC.3 +++ b/docs/libcurl/opts/CURLOPT_ALTSVC.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ALTSVC 3 "August 14, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ALTSVC 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_ALTSVC \- set alt-svc cache file name +CURLOPT_ALTSVC \- alt-svc cache file name .SH SYNOPSIS .nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC, char *filename); .fi -.SH EXPERIMENTAL -Warning: this feature is early code and is marked as experimental. It can only -be enabled by explicitly telling configure with \fB--enable-alt-svc\fP. You are -advised to not ship this in production before the experimental label is -removed. .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 diff --git a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 index a14737d98..ba06362b6 100644 --- a/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 +++ b/docs/libcurl/opts/CURLOPT_ALTSVC_CTRL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ALTSVC_CTRL 3 "February 11, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ALTSVC_CTRL 3 "November 04, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_ALTSVC_CTRL \- control alt-svc behavior @@ -28,7 +28,6 @@ CURLOPT_ALTSVC_CTRL \- control alt-svc behavior .nf #include <curl/curl.h> -#define CURLALTSVC_IMMEDIATELY (1<<0) #define CURLALTSVC_READONLYFILE (1<<2) #define CURLALTSVC_H1 (1<<3) #define CURLALTSVC_H2 (1<<4) @@ -36,25 +35,20 @@ CURLOPT_ALTSVC_CTRL \- control alt-svc behavior CURLcode curl_easy_setopt(CURL *handle, CURLOPT_ALTSVC_CTRL, long bitmask); .fi -.SH EXPERIMENTAL -Warning: this feature is early code and is marked as experimental. It can only -be enabled by explicitly telling configure with \fB--enable-alt-svc\fP. You are -advised to not ship this in production before the experimental label is -removed. .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 will only accept Alt-Svc headers over a secure transport, meaning +libcurl only accepts Alt-Svc headers over a secure transport, meaning HTTPS. It will also only complete 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 +will be preferred. + Setting any bit will enable the alt-svc engine. -.IP "CURLALTSVC_IMMEDIATELY" -If an Alt-Svc: header is received, this instructs libcurl to switch to one of -those alternatives asap rather than to save it and use for the next -request. (Not currently supported). .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 diff --git a/docs/libcurl/opts/CURLOPT_APPEND.3 b/docs/libcurl/opts/CURLOPT_APPEND.3 index 8f0724e82..68b87c953 100644 --- a/docs/libcurl/opts/CURLOPT_APPEND.3 +++ b/docs/libcurl/opts/CURLOPT_APPEND.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_APPEND 3 "March 06, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_APPEND 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_APPEND \- enable appending to the remote file +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. diff --git a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 index c020fe1e8..9e9a83796 100644 --- a/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 +++ b/docs/libcurl/opts/CURLOPT_AUTOREFERER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_AUTOREFERER 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_AUTOREFERER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 parameter set to 1 to enable this. When enabled, libcurl will -automatically set the Referer: header field in HTTP requests where it follows -a Location: redirect. +automatically set the Referer: header field in HTTP requests to the full URL +where it follows a Location: redirect. .SH DEFAULT 0, disabled .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 new file mode 100644 index 000000000..76d54ac22 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_AWS_SIGV4.3 @@ -0,0 +1,98 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_AWS_SIGV4 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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. +.PP +Pass a char * that is the collection of specific arguments are used for +creating outgoing authentication headers. +The format of the param 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 host name specified in the URL if omitted. +.IP service +The argument is a function provided by a cloud. +It is extracted from the host name 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 "aws:amz" in parameter. +.PP +Example with "Test:Try", when curl will do the algorithm, it will generate +"TEST-HMAC-SHA256" for "Algorithm", "x-try-date" and "X-Try-Date" for "date", +"test4_request" for "request type", +"SignedHeaders=content-type;host;x-try-date" for "signed headers" +.PP +If you use just "test", instead of "test:try", +test will be use for every strings generated +.SH DEFAULT +By default, the value of this parameter is NULL. +Calling \fICURLOPT_HTTPAUTH(3)\fP with CURLAUTH_AWS_SIGV4 is the same +as calling this with "aws:amz" in parameter. +.SH PROTOCOLS +HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); + +struct curl_slist *list = NULL; + +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, + "https://service.region.example.com/uri"); + curl_easy_setopt(c, CURLOPT_AWS_SIGV4, "provider1:provider2"); + + /* service and region also could be set in CURLOPT_AWS_SIGV4 */ + /* + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/uri"); + curl_easy_setopt(c, CURLOPT_AWS_SIGV4, + "provider1:provider2:region:service"); + */ + + curl_easy_setopt(c, CURLOPT_USERPWD, "MY_ACCESS_KEY:MY_SECRET_KEY"); + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.75.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH NOTES +This option overrides the other auth types you might have set in CURL_HTTPAUTH +which should be highlighted as this makes this auth method special. +This method cannot be combined with other auth types. +.SH "SEE ALSO" +.BR CURLOPT_HEADEROPT "(3), " CURLOPT_HTTPHEADER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 index 70bea72d7..ad15da8b8 100644 --- a/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_BUFFERSIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_BUFFERSIZE 3 "May 13, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_BUFFERSIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_BUFFERSIZE \- set preferred receive buffer size +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 @@ -40,6 +42,9 @@ 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 (512kB). 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. .SH DEFAULT CURL_MAX_WRITE_SIZE (16kB) .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3 index a3b5719d9..ac752c3ba 100644 --- a/docs/libcurl/opts/CURLOPT_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_CAINFO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CAINFO 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CAINFO 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * to a null-terminated string naming a file holding one or more certificates to verify the peer with. @@ -74,11 +76,11 @@ if(curl) { } .fi .SH AVAILABILITY -For the SSL engines that don't support certificate files the CURLOPT_CAINFO +For the SSL engines that do not support certificate files the CURLOPT_CAINFO option is ignored. Schannel support added in libcurl 7.60. .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. .SH "SEE ALSO" -.BR CURLOPT_CAPATH "(3), " +.BR CURLOPT_CAINFO_BLOB "(3), " CURLOPT_CAPATH "(3), " .BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 new file mode 100644 index 000000000..37a51b419 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_CAINFO_BLOB.3 @@ -0,0 +1,72 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_CAINFO_BLOB 3 "November 29, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server's certificate, \fICURLOPT_CAINFO_BLOB(3)\fP is not needed. + +This option overrides \fICURLOPT_CAINFO(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. +.SH EXAMPLE +.nf +char *strpem; /* strpem must point to a PEM string */ +CURL *curl = curl_easy_init(); +if(curl) { + 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); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in 7.77.0. + +This option is supported by the BearSSL (since 7.79.0), mbedTLS (since 7.81.0), +OpenSSL, Secure Transport and Schannel backends. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_CAINFO "(3), " CURLOPT_CAPATH "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.3 b/docs/libcurl/opts/CURLOPT_CAPATH.3 index 00c7d6270..3e5883537 100644 --- a/docs/libcurl/opts/CURLOPT_CAPATH.3 +++ b/docs/libcurl/opts/CURLOPT_CAPATH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CAPATH 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CAPATH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CAPATH \- specify directory holding CA certificates +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 * to a null-terminated string naming a directory holding multiple CA certificates to verify the peer with. If libcurl is built against OpenSSL, @@ -41,7 +43,7 @@ to some limitation in openssl. The application does not have to keep the string around after setting this option. .SH DEFAULT -NULL +A default path detected at build time. .SH PROTOCOLS All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.3 b/docs/libcurl/opts/CURLOPT_CERTINFO.3 index d406c7142..be212d973 100644 --- a/docs/libcurl/opts/CURLOPT_CERTINFO.3 +++ b/docs/libcurl/opts/CURLOPT_CERTINFO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CERTINFO 3 "January 29, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CERTINFO 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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's certificate chain info gatherer. With this enabled, libcurl will extract lots of information and data about the @@ -71,8 +73,9 @@ if(curl) { } .fi .SH AVAILABILITY -This option is supported by the OpenSSL, GnuTLS, Schannel, NSS and GSKit -backends. +This option is supported by the OpenSSL, GnuTLS, Schannel, NSS, GSKit and +Secure Transport backends. Schannel support added in 7.50.0. Secure Transport +support added in 7.79.0. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 index a49568dcf..f2ed16786 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_BGN_FUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CHUNK_BGN_FUNCTION 3 "May 03, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CHUNK_BGN_FUNCTION 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_CHUNK_BGN_FUNCTION \- callback before a transfer with FTP wildcardmatch diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 index c92002ce6..82e722aba 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_DATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CHUNK_DATA 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CHUNK_DATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CHUNK_DATA \- custom pointer to the FTP chunk callbacks +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 will be untouched by libcurl and passed as the ptr argument to the \fICURLOPT_CHUNK_BGN_FUNCTION(3)\fP and diff --git a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 index c680aecad..821791b57 100644 --- a/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CHUNK_END_FUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CHUNK_END_FUNCTION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CHUNK_END_FUNCTION 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_CHUNK_END_FUNCTION \- callback after a transfer with FTP wildcardmatch diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 index 4399b39ef..928c8e1b7 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CLOSESOCKETDATA 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CLOSESOCKETDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CLOSESOCKETDATA, + void *pointer); +.fi .SH DESCRIPTION Pass a \fIpointer\fP that will be untouched by libcurl and passed as the first argument in the closesocket callback set with diff --git a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 index a5c16a96e..043265c27 100644 --- a/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CLOSESOCKETFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,16 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CLOSESOCKETFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CLOSESOCKETFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CLOSESOCKETFUNCTION \- callback to socket close replacement function +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); +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. diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 index f63fd3060..279b54af7 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONNECTTIMEOUT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONNECTTIMEOUT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 should contain the maximum time in seconds that you allow the connection phase to the server to take. This only limits the connection diff --git a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 index 03c41099d..a80704ef5 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECTTIMEOUT_MS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONNECTTIMEOUT_MS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONNECTTIMEOUT_MS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CONNECTTIMEOUT_MS, + long timeout); +.fi .SH DESCRIPTION Pass a long. It should contain the maximum time in milliseconds that you allow the connection phase to the server to take. This only limits the connection diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 index 60ca53526..9ebab8bf6 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECT_ONLY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONNECT_ONLY 3 "February 18, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONNECT_ONLY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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, diff --git a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 index ecf3d42b9..dfe5c13d3 100644 --- a/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 +++ b/docs/libcurl/opts/CURLOPT_CONNECT_TO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONNECT_TO 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONNECT_TO 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CONNECT_TO \- Connect to a specific host and port instead of the URL's host and port +CURLOPT_CONNECT_TO \- connect to a specific host and port instead of the URL's host and port .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 index 3d23dec94..7897a6ff5 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_NETWORK_FUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONV_FROM_NETWORK_FUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_CONV_FROM_NETWORK_FUNCTION \- convert data from network to host encoding @@ -50,7 +50,7 @@ should be returned if an error was encountered. network encoding. It is used when commands or ASCII data are received over the network. -If you set a callback pointer to NULL, or don't set it at all, the built-in +If you set a callback pointer to NULL, or do not set it at all, the built-in libcurl iconv functions will be used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, conversion will return the CURLE_CONV_REQD error code. diff --git a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 index 8fd45af29..aa7aad487 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_FROM_UTF8_FUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONV_FROM_UTF8_FUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_CONV_FROM_UTF8_FUNCTION \- convert data from UTF8 to host encoding @@ -49,7 +49,7 @@ should be returned if an error was encountered. \fBCURLOPT_CONV_FROM_UTF8_FUNCTION\fP converts to host encoding from UTF8 encoding. It is required only for SSL processing. -If you set a callback pointer to NULL, or don't set it at all, the built-in +If you set a callback pointer to NULL, or do not set it at all, the built-in libcurl iconv functions will be used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, conversion will return the CURLE_CONV_REQD error code. diff --git a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 index fb682b2ff..e510cfd6d 100644 --- a/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_CONV_TO_NETWORK_FUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CONV_TO_NETWORK_FUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_CONV_TO_NETWORK_FUNCTION \- convert data to network from host encoding @@ -50,7 +50,7 @@ should be returned if an error was encountered. network encoding. It is used when commands or ASCII data are sent over the network. -If you set a callback pointer to NULL, or don't set it at all, the built-in +If you set a callback pointer to NULL, or do not set it at all, the built-in libcurl iconv functions will be used. If HAVE_ICONV was not defined when libcurl was built, and no callback has been established, conversion will return the CURLE_CONV_REQD error code. diff --git a/docs/libcurl/opts/CURLOPT_COOKIE.3 b/docs/libcurl/opts/CURLOPT_COOKIE.3 index c169efaa0..72803d0d8 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COOKIE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COOKIE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_COOKIE \- set contents of HTTP Cookie header +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 will be used to set a cookie in the HTTP request. The format of the string should be @@ -43,7 +45,7 @@ similar, they will 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 will not be modified by it. If you enable the -cookie engine and either you've imported a cookie of the same name (e.g. 'foo') +cookie engine and either you have imported a cookie of the same name (e.g. 'foo') or the server has set one, it will have no effect on the cookies you set here. A request to the server will send both the 'foo' held by the cookie engine and the 'foo' held by this option. To set a cookie that is instead held by the diff --git a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 index fc4bf93a6..8e9496f59 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEFILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COOKIEFILE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COOKIEFILE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_COOKIEFILE \- file name 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 file name of your file holding cookie data to read. The cookie data can be @@ -45,19 +47,19 @@ libcurl will instead read from stdin. This option only \fBreads\fP cookies. To make libcurl write cookies to file, see \fICURLOPT_COOKIEJAR(3)\fP. -Exercise caution if you are using this option and multiple transfers may occur. -If you use the Set-Cookie format and don't 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 then both -will be sent on a future transfer to that server, likely not what you intended. -To address these issues set a domain in Set-Cookie (doing that will include -sub-domains) or use the Netscape format. +If you use the Set-Cookie file format and do not specify a domain then the +cookie is not sent since the domain will never match. To address this, set a +domain in Set-Cookie line (doing that will include sub-domains) or preferably: +use the Netscape format. If you use this option multiple times, you just add more files to read. Subsequent files will add more cookies. The application does not have to keep the string around after setting this option. + +Setting this option to NULL will (since 7.77.0) explicitly disable the cookie +engine and clear the list of files to read cookies from. .SH DEFAULT NULL .SH PROTOCOLS @@ -79,7 +81,7 @@ if(curl) { .SH "Cookie file format" The cookie file format and general cookie concepts in curl are described in the HTTP-COOKIES.md file, also hosted online here: -https://curl.haxx.se/docs/http-cookies.html +https://curl.se/docs/http-cookies.html .SH AVAILABILITY As long as HTTP is supported .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 index c5c4294b9..4ebcaddff 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIEJAR.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COOKIEJAR 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COOKIEJAR 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_COOKIEJAR \- file name 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 char *, null-terminated. This will make libcurl write all internally known cookies to the specified file when @@ -36,10 +38,10 @@ 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 location it will make matching cookies get sent accordingly. -Note that libcurl doesn't read any cookies from the cookie jar. If you want to +Note that libcurl does not read any cookies from the cookie jar. If you want to read cookies from a file, use \fICURLOPT_COOKIEFILE(3)\fP. -If the cookie jar file can't be created or written to (when the +If the cookie jar file cannot be created or written to (when the \fIcurl_easy_cleanup(3)\fP is called), libcurl will not and cannot report an error for this. Using \fICURLOPT_VERBOSE(3)\fP or \fICURLOPT_DEBUGFUNCTION(3)\fP will get a warning to display, but that is the diff --git a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 index 007baf5c4..d2c6422a8 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIELIST.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIELIST.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COOKIELIST 3 "January 10, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COOKIELIST 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_COOKIELIST \- add to or manipulate cookies held in memory @@ -38,10 +38,10 @@ regular HTTP-style header (Set-Cookie: ...) format. This will also enable the cookie engine. This adds that single cookie to the internal cookie store. Exercise caution if you are using this option and multiple transfers may occur. -If you use the Set-Cookie format and don't specify a domain then the cookie is +If you use the Set-Cookie format and do 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've imported one) then both will be sent on a future transfer to that +you have imported one) then both will be sent on a future transfer to that server, likely not what you intended. To address these issues set a domain in Set-Cookie (doing that will include sub-domains) or use the Netscape format as shown in EXAMPLE. @@ -91,7 +91,7 @@ curl_easy_setopt(curl, CURLOPT_COOKIELIST, my_cookie); 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 won't be replaced by one read from a file. +cookie. A live cookie will not be replaced by one read from a file. */ curl_easy_setopt(curl, CURLOPT_COOKIEFILE, "cookies.txt"); /* import */ @@ -108,7 +108,7 @@ curl_easy_cleanup(curl); /* cookies exported to cookies.txt */ .SH "Cookie file format" The cookie file format and general cookie concepts in curl are described in the HTTP-COOKIES.md file, also hosted online here: -https://curl.haxx.se/docs/http-cookies.html +https://curl.se/docs/http-cookies.html .SH AVAILABILITY ALL was added in 7.14.1 diff --git a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 index d3a57b078..e8a7f9abf 100644 --- a/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 +++ b/docs/libcurl/opts/CURLOPT_COOKIESESSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COOKIESESSION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COOKIESESSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will force libcurl to ignore all cookies it is about to load that are "session cookies" @@ -48,7 +50,7 @@ CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - /* new "session", don't load session cookies */ + /* new "session", do not load session cookies */ curl_easy_setopt(curl, CURLOPT_COOKIESESSION, 1L); /* get the (non session) cookies from this file */ diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 index 98be4328a..625d70f1a 100644 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_COPYPOSTFIELDS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_COPYPOSTFIELDS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * 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 diff --git a/docs/libcurl/opts/CURLOPT_CRLF.3 b/docs/libcurl/opts/CURLOPT_CRLF.3 index 8a5912fa4..6df1da8e5 100644 --- a/docs/libcurl/opts/CURLOPT_CRLF.3 +++ b/docs/libcurl/opts/CURLOPT_CRLF.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CRLF 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CRLF 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CRLF \- enable/disable CRLF conversion +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 diff --git a/docs/libcurl/opts/CURLOPT_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_CRLFILE.3 index b8995d2d8..66420f79e 100644 --- a/docs/libcurl/opts/CURLOPT_CRLFILE.3 +++ b/docs/libcurl/opts/CURLOPT_CRLFILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CRLFILE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CRLFILE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CRLFILE \- specify a Certificate Revocation List file +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 * to a null-terminated string naming a \fIfile\fP with the concatenation of CRL (in PEM format) to use in the certificate validation that diff --git a/docs/libcurl/opts/CURLOPT_CURLU.3 b/docs/libcurl/opts/CURLOPT_CURLU.3 index d5e1d7fec..20cb28ce1 100644 --- a/docs/libcurl/opts/CURLOPT_CURLU.3 +++ b/docs/libcurl/opts/CURLOPT_CURLU.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CURLU 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CURLU 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CURLU \- set URL with CURLU * +CURLOPT_CURLU \- URL in CURLU * format .SH SYNOPSIS +.nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CURLU, void *pointer); +.fi .SH DESCRIPTION Pass in a pointer to the \fIURL\fP to work with. The parameter should be a CURLU *. Setting \fICURLOPT_CURLU(3)\fP will explicitly override @@ -37,9 +39,9 @@ CURLU *. Setting \fICURLOPT_CURLU(3)\fP will explicitly override transfer is started. libcurl will use this handle and its contents read-only and will not change -its contents. An application can very well update the contents of the URL -handle after a transfer is done and if the same handle is then used in a -subsequent request the updated contents will then be used. +its contents. An application can update the contents of the URL handle after a +transfer is done and if the same handle is then used in a subsequent request +the updated contents will then be used. .SH DEFAULT The default value of this parameter is NULL. .SH PROTOCOLS @@ -68,3 +70,4 @@ Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_URL "(3), " .BR curl_url "(3), " curl_url_get "(3), " curl_url_set "(3), " +.BR curl_url_dup "(3), " curl_url_cleanup "(3), " curl_url_strerror "(3)" diff --git a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 index 77da01bb4..60f2c74a2 100644 --- a/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_CUSTOMREQUEST 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_CUSTOMREQUEST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_CUSTOMREQUEST \- custom string for request +CURLOPT_CUSTOMREQUEST \- custom request method .SH SYNOPSIS +.nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *request); +.fi .SH DESCRIPTION Pass a pointer to a null-terminated string as parameter. When you change the request method by setting \fICURLOPT_CUSTOMREQUEST(3)\fP -to something, you don't actually change how libcurl behaves or acts in regards +to something, you do not actually change how libcurl behaves or acts in regards to the particular request method, it will only change the actual string sent in the request. diff --git a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 index 1a6e8f52c..7a9e6dd29 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 +++ b/docs/libcurl/opts/CURLOPT_DEBUGDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DEBUGDATA 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DEBUGDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DEBUGDATA \- custom pointer for debug callback +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 @@ -37,7 +39,31 @@ NULL .SH PROTOCOLS All .SH EXAMPLE -https://curl.haxx.se/libcurl/c/debug.html +.nf +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 Always .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 index 9b6f984c6..4eca3766a 100644 --- a/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_DEBUGFUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DEBUGFUNCTION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DEBUGFUNCTION 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_DEBUGFUNCTION \- debug callback diff --git a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 index 3a2c33d37..0802421c0 100644 --- a/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,16 +20,18 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DEFAULT_PROTOCOL 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DEFAULT_PROTOCOL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 index ad496d73c..d8e524ede 100644 --- a/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 +++ b/docs/libcurl/opts/CURLOPT_DIRLISTONLY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,23 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DIRLISTONLY 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DIRLISTONLY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 behaviour +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. @@ -43,7 +45,7 @@ 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 -doesn't end with a slash, which otherwise is necessary. +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 will effectively break that feature then. diff --git a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 index 0a00131af..3746d5bab 100644 --- a/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 +++ b/docs/libcurl/opts/CURLOPT_DISALLOW_USERNAME_IN_URL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DISALLOW_USERNAME_IN_URL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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. @@ -47,7 +50,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.61.0 +Added in 7.61.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. diff --git a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 index db2d648bb..31da9f7a1 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_CACHE_TIMEOUT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,27 +20,29 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_CACHE_TIMEOUT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DNS_CACHE_TIMEOUT \- set life-time for DNS cache entries +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 resolves will be 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. -The name resolve functions of various libc implementations don't re-read name +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. -Note that DNS entries have a "TTL" property but libcurl doesn't use that. This +Note that DNS entries have a "TTL" property but libcurl does not use that. This DNS cache timeout is entirely speculative that a name will resolve to the same address for a certain small amount of time into the future. .SH DEFAULT @@ -53,7 +55,7 @@ CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - /* only reuse addresses for a very short time */ + /* only reuse addresses for a short time */ curl_easy_setopt(curl, CURLOPT_DNS_CACHE_TIMEOUT, 2L); ret = curl_easy_perform(curl); diff --git a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 index a675ca816..f61b25d1f 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_INTERFACE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_INTERFACE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_INTERFACE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DNS_INTERFACE \- set interface to speak DNS over +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 * 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 (don't bind to a specific +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 diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 index 18f9a51af..085ef8c2c 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_LOCAL_IP4 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_LOCAL_IP4 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 (don't bind +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 diff --git a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 index 5acb8f67b..04f58c5d3 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,20 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_LOCAL_IP6 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_LOCAL_IP6 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 (don't bind to 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 diff --git a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 index 7ad020b62..4b08526b0 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_SERVERS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_SERVERS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_SERVERS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DNS_SERVERS \- set preferred DNS servers +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 * that is the list of DNS servers to be used instead of the system -default. The format of the dns servers option is: +default. The format of the dns servers option is: host[:port][,host[:port]]... diff --git a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 index 74011b404..7dedd9c50 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_SHUFFLE_ADDRESSES.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "March 17, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_SHUFFLE_ADDRESSES 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DNS_SHUFFLE_ADDRESSES \- Shuffle addresses when a hostname returns more than one +CURLOPT_DNS_SHUFFLE_ADDRESSES \- shuffle IP addresses for hostname .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 index c098a618a..20b1dd97e 100644 --- a/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 +++ b/docs/libcurl/opts/CURLOPT_DNS_USE_GLOBAL_CACHE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "March 07, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DNS_USE_GLOBAL_CACHE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_DNS_USE_GLOBAL_CACHE \- enable/disable global DNS cache +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 note use! +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 will survive between easy handle creations and deletions. This is diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 new file mode 100644 index 000000000..93880dde7 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYHOST.3 @@ -0,0 +1,89 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_DOH_SSL_VERIFYHOST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.SH NAME +CURLOPT_DOH_SSL_VERIFYHOST \- verify the host name 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's certificate name fields against the host name. + +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 host name 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 VERIFYHOST 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. If libcurl is built against NSS and +\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP is zero, +\fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP is also set to zero and cannot be +overridden. +.SH DEFAULT +2 +.SH PROTOCOLS +DoH +.SH EXAMPLE +.nf +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 7.76.0 + +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), " +.BR CURLOPT_SSL_VERIFYHOST "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " +.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " +.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 new file mode 100644 index 000000000..458a4641c --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYPEER.3 @@ -0,0 +1,100 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_DOH_SSL_VERIFYPEER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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's 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 host name in the certificate is valid for the host name 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 +DoH +.SH EXAMPLE +.nf +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 7.76.0 + +If built TLS enabled. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), " +.BR CURLOPT_SSL_VERIFYHOST "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " +.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " +.BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), " +.BR CURLOPT_CAINFO "(3), " +.BR CURLOPT_CAPATH "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 new file mode 100644 index 000000000..97a8ce2d6 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_DOH_SSL_VERIFYSTATUS.3 @@ -0,0 +1,73 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_DOH_SSL_VERIFYSTATUS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.SH NAME +CURLOPT_DOH_SSL_VERIFYSTATUS \- verify the DoH SSL certificate's 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. + +Note that if this option is enabled but the server does not support the TLS +extension, the verification will fail. +.SH DEFAULT +0 +.SH PROTOCOLS +DoH +.SH EXAMPLE +.nf +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 7.76.0. This option is currently only supported by the OpenSSL, GnuTLS +and NSS TLS backends. +.SH RETURN VALUE +Returns CURLE_OK if OCSP stapling is supported by the SSL backend, otherwise +returns CURLE_NOT_BUILT_IN. +.SH "SEE ALSO" +.BR CURLOPT_DOH_SSL_VERIFYHOST "(3), " +.BR CURLOPT_DOH_SSL_VERIFYPEER "(3), " +.BR CURLOPT_SSL_VERIFYSTATUS "(3), " diff --git a/docs/libcurl/opts/CURLOPT_DOH_URL.3 b/docs/libcurl/opts/CURLOPT_DOH_URL.3 index 007f4c2c4..d43e4c546 100644 --- a/docs/libcurl/opts/CURLOPT_DOH_URL.3 +++ b/docs/libcurl/opts/CURLOPT_DOH_URL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2018 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,33 +20,44 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_DOH_URL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_DOH_URL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 +Pass in a pointer to a \fIURL\fP for the DoH server to use for name resolving. The parameter should be a char * to a null-terminated string which must be URL-encoded in the following format: "https://host:port/path". It MUST specify a HTTPS URL. -libcurl doesn't validate the syntax or use this variable until the transfer is +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 will still return \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 +To find the DoH server itself, which might be specified using a name, libcurl will use the default name lookup function. You can bootstrap that by providing -the address for the DOH server with \fICURLOPT_RESOLVE(3)\fP. +the address for the DoH server with \fICURLOPT_RESOLVE(3)\fP. + +Disable DoH use again by setting this option to NULL. +.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. -Disable DOH use again by setting this option to NULL. +A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited. .SH DEFAULT -NULL - there is no default DOH URL. If this option isn't set, libcurl will use +NULL - there is no default DoH URL. If this option is not set, libcurl will use the default name resolver. .SH PROTOCOLS All @@ -65,8 +76,8 @@ Added in 7.62.0 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so -given a bad DOH URL, curl will not detect a problem until it tries to resolve +Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so +given a bad DoH URL, curl will not detect a problem until it tries to resolve a name with it. .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_RESOLVE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 index bf59784ea..79ac8ba70 100644 --- a/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 +++ b/docs/libcurl/opts/CURLOPT_EGDSOCKET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_EGDSOCKET 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_EGDSOCKET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_EGDSOCKET \- set EGD socket path +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 Pass a char * to the null-terminated path name to the Entropy Gathering Daemon -socket. It will be used to seed the random engine for SSL. +socket. It will be used to seed the random engine for TLS. The application does not have to keep the string around after setting this option. @@ -49,7 +51,7 @@ if(curl) { } .fi .SH AVAILABILITY -If built TLS enabled. Only the OpenSSL and GnuTLS backends will use this. +If built with TLS enabled. Only the OpenSSL backend will use this. .SH RETURN VALUE Returns CURLE_OK if TLS is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 index 17f2bc780..432d0e052 100644 --- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 +++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ERRORBUFFER 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ERRORBUFFER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_ERRORBUFFER \- set error buffer for error messages +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 * to a buffer that libcurl \fBmay\fP store human readable error messages on failures or problems. This may be more helpful than just the @@ -35,9 +37,9 @@ return code from \fIcurl_easy_perform(3)\fP and related functions. The buffer \fBmust be at least CURL_ERROR_SIZE bytes big\fP. You must keep the associated buffer available until libcurl no longer needs -it. Failing to do so will cause very odd behavior or even crashes. libcurl -will need it until you call \fIcurl_easy_cleanup(3)\fP or you set the same -option again to use a different pointer. +it. Failing to do so will cause odd behavior or even crashes. libcurl will +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 will initialize the contents of the error buffer to an @@ -90,4 +92,4 @@ Returns CURLE_OK .SH "SEE ALSO" .BR CURLOPT_DEBUGFUNCTION "(3), " CURLOPT_VERBOSE "(3), " .BR curl_easy_strerror "(3), " curl_multi_strerror "(3), " -.BR curl_share_strerror "(3) " +.BR curl_share_strerror "(3), " curl_url_strerror "(3)" diff --git a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 index c33f324bb..f5468b871 100644 --- a/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_EXPECT_100_TIMEOUT_MS.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_EXPECT_100_TIMEOUT_MS 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_EXPECT_100_TIMEOUT_MS \- timeout for Expect: 100-continue response diff --git a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 index 8d15b4fee..8bf837058 100644 --- a/docs/libcurl/opts/CURLOPT_FAILONERROR.3 +++ b/docs/libcurl/opts/CURLOPT_FAILONERROR.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FAILONERROR 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FAILONERROR 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_FILETIME.3 b/docs/libcurl/opts/CURLOPT_FILETIME.3 index 1f33d67f6..194c8b21c 100644 --- a/docs/libcurl/opts/CURLOPT_FILETIME.3 +++ b/docs/libcurl/opts/CURLOPT_FILETIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FILETIME 3 "April 03, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FILETIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will attempt to get the modification time of the remote document in this operation. This requires that the remote server diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 index c41be716d..ac0d09ef0 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_DATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FNMATCH_DATA 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FNMATCH_DATA 3 "November 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FNMATCH_DATA \- custom pointer to fnmatch callback +CURLOPT_FNMATCH_DATA \- pointer passed to the fnmatch callback .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 index afa6febde..29190c225 100644 --- a/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_FNMATCH_FUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FNMATCH_FUNCTION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FNMATCH_FUNCTION 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FNMATCH_FUNCTION \- wildcard matching function callback +CURLOPT_FNMATCH_FUNCTION \- wildcard match callback .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 index aa656257b..e44f93d12 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FOLLOWLOCATION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FOLLOWLOCATION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_FOLLOWLOCATION \- follow HTTP 3xx redirects .SH SYNOPSIS +.nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FOLLOWLOCATION, long enable); +.fi .SH DESCRIPTION A long parameter set to 1 tells the library to follow any Location: header that the server sends as part of an HTTP header in a 3xx response. The @@ -52,7 +54,7 @@ dictates which request method it will use in the subsequent request: For 301, will make libcurl send the same method again. For users who think the existing location following is too naive, too simple -or just lacks features, it is very easy to instead implement your own redirect +or just lacks features, it is easy to instead implement your own redirect follow logic with the use of \fIcurl_easy_getinfo(3)\fP's \fICURLINFO_REDIRECT_URL(3)\fP option instead of using \fICURLOPT_FOLLOWLOCATION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 index 0830b5fe3..2b4bdc283 100644 --- a/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 +++ b/docs/libcurl/opts/CURLOPT_FORBID_REUSE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FORBID_REUSE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FORBID_REUSE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 @@ -58,3 +60,4 @@ Always Returns CURLE_OK .SH "SEE ALSO" .BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXCONNECTS "(3), " +.BR CURLOPT_MAXLIFETIME_CONN "(3), " diff --git a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 index 408b11e69..3d30fea9f 100644 --- a/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 +++ b/docs/libcurl/opts/CURLOPT_FRESH_CONNECT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FRESH_CONNECT 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FRESH_CONNECT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 re-use an existing one. This option should be @@ -35,7 +37,7 @@ used with caution and only if you understand what it does as it may seriously impact performance. Related functionality is \fICURLOPT_FORBID_REUSE(3)\fP which makes sure the -connection is closed after use so that it won't be re-used. +connection is closed after use so that it will not be re-used. Set \fIfresh\fP to 0 to have libcurl attempt re-using an existing connection (default behavior). diff --git a/docs/libcurl/opts/CURLOPT_FTPPORT.3 b/docs/libcurl/opts/CURLOPT_FTPPORT.3 index 66f65e507..55ff84cc9 100644 --- a/docs/libcurl/opts/CURLOPT_FTPPORT.3 +++ b/docs/libcurl/opts/CURLOPT_FTPPORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTPPORT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTPPORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will be made actively and the given string will be used to get @@ -37,7 +39,7 @@ The PORT instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a host name, a network interface name (under Unix) or just a '-' symbol to let the library use your system's default IP address. Default FTP operations are passive, and thus -won't use PORT. +will not use PORT. The address can be followed by a ':' to specify a port, optionally followed by a '-' to specify a port range. If the port specified is 0, the operating diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 index 79a14c8a6..19e8258e0 100644 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTPSSLAUTH 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTPSSLAUTH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTPSSLAUTH \- set order in which to attempt TLS vs SSL when using FTP +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 diff --git a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 index 47d46f389..e6f620fdf 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_ACCOUNT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_ACCOUNT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTP_ACCOUNT \- set account info for FTP +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 user name and password has been provided, diff --git a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 index 0ef996f13..3f8adf03c 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_ALTERNATIVE_TO_USER.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_ALTERNATIVE_TO_USER 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_FTP_ALTERNATIVE_TO_USER \- command to use instead of USER with FTP diff --git a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 index e037d984b..ba687621a 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_CREATE_MISSING_DIRS.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_CREATE_MISSING_DIRS 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_FTP_CREATE_MISSING_DIRS \- create missing dirs for FTP and SFTP @@ -45,13 +45,13 @@ For FTP requests, that means a CWD command fails. CWD being the command that changes working directory. For SFTP requests, libcurl will attempt to create the remote directory if it -can't obtain a handle to the target-location. The creation will fail if a file +cannot obtain a handle to the target-location. The creation will fail 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 MKD command fails. This is -especially useful if you're doing many simultaneous connections against the +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 MKD before this connection and thus MKD fails but trying CWD works! diff --git a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 index 1c7059f9c..122036737 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_FILEMETHOD.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_FILEMETHOD 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_FILEMETHOD 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_FTP_FILEMETHOD \- select directory traversing method for FTP @@ -34,7 +34,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_FILEMETHOD, 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 aren't compliant to +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: diff --git a/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 index 739c26188..e00ca8cb5 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_RESPONSE_TIMEOUT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_RESPONSE_TIMEOUT 3 "October 03, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_RESPONSE_TIMEOUT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_FTP_RESPONSE_TIMEOUT \- time allowed to wait for FTP response .SH SYNOPSIS +.nf #include <curl/curl.h> -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_RESPONSE_TIMEOUT, long timeout); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTP_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 diff --git a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 index 8fb839e44..315a63694 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_SKIP_PASV_IP.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_SKIP_PASV_IP 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_SKIP_PASV_IP 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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's PASV command when @@ -36,11 +38,13 @@ address it already uses for the control connection. But it will use the port number from the 227-response. This option thus allows libcurl to work around broken server installations -that due to NATs, firewalls or incompetence report the wrong IP address back. +that due to NATs, firewalls or incompetence report the wrong IP address +back. Setting the 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 -0 +1 since 7.74.0, was 0 before then. .SH PROTOCOLS FTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 index febf31158..5134a0bd0 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_SSL_CCC.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,22 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_SSL_CCC 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_SSL_CCC 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will be unencrypted. This allows NAT routers to follow the FTP transaction. Pass a long using one of the values below .IP CURLFTPSSL_CCC_NONE -Don't attempt to use CCC. +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. diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 index c29d03d4d..d426e623a 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPRT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_USE_EPRT 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_USE_EPRT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTP_USE_EPRT \- enable/disable use of EPRT with FTP +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 @@ -40,6 +42,22 @@ necessary then. .SH DEFAULT .SH PROTOCOLS .SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + 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); + + ret = curl_easy_perform(curl); + + curl_easy_cleanup(curl); +} +.fi .SH AVAILABILITY Added in 7.10.5 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 index 9a00ef357..40297a149 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_EPSV.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_USE_EPSV 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_USE_EPSV 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTP_USE_EPSV \- enable/disable use of EPSV +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 diff --git a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 index aa3e51516..20275ef98 100644 --- a/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 +++ b/docs/libcurl/opts/CURLOPT_FTP_USE_PRET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_FTP_USE_PRET 3 "May 05, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_FTP_USE_PRET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_FTP_USE_PRET \- enable the PRET command +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 diff --git a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 index f3c4b0ec7..0af78e9ea 100644 --- a/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 +++ b/docs/libcurl/opts/CURLOPT_GSSAPI_DELEGATION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_GSSAPI_DELEGATION 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_GSSAPI_DELEGATION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_GSSAPI_DELEGATION \- set allowed GSS-API delegation +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 diff --git a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 index ef843d004..a502a062c 100644 --- a/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HAPPY_EYEBALLS_TIMEOUT_MS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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 @@ -41,6 +44,8 @@ Eyeballs RFC 6555 says "It is RECOMMENDED that connection attempts be paced currently defaults to 200 ms. Firefox and Chrome currently default to 300 ms. .SH DEFAULT CURL_HET_DEFAULT (currently defined as 200L) +.SH PROTOCOLS +All except FILE .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -58,3 +63,6 @@ if(curl) { Added in 7.59.0 .SH RETURN VALUE Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_CONNECTTIMEOUT_MS "(3), " +.BR CURLOPT_TIMEOUT "(3), " CURLOPT_LOW_SPEED_LIMIT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 index 843f75cc7..94a329651 100644 --- a/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 +++ b/docs/libcurl/opts/CURLOPT_HAPROXYPROTOCOL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HAPROXYPROTOCOL 3 "May 18, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HAPROXYPROTOCOL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 @@ -56,3 +58,5 @@ if(curl) { Along with HTTP. Added in 7.60.0. .SH RETURN VALUE Returns CURLE_OK if HTTP is enabled, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_PROXY "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HEADER.3 b/docs/libcurl/opts/CURLOPT_HEADER.3 index 4a7c5d2f9..330395128 100644 --- a/docs/libcurl/opts/CURLOPT_HEADER.3 +++ b/docs/libcurl/opts/CURLOPT_HEADER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HEADER 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HEADER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 @@ -63,6 +65,8 @@ if(curl) { curl_easy_perform(curl); } .fi +.SH AVAILABILITY +Provided in all libcurl versions. .SH RETURN VALUE Returns CURLE_OK. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 index af3b8c7ee..fe4593069 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERDATA.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HEADERDATA 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HEADERDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. diff --git a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 index 9b2ce77d5..62d6740de 100644 --- a/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_HEADERFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,11 +20,12 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HEADERFUNCTION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HEADERFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_HEADERFUNCTION \- callback that receives header data .SH SYNOPSIS +.nf #include <curl/curl.h> size_t header_callback(char *buffer, @@ -32,23 +33,25 @@ size_t header_callback(char *buffer, size_t nitems, void *userdata); -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HEADERFUNCTION, header_callback); +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 function gets called by libcurl as soon as it has received header data. The header callback will be called once for each header and only -complete header lines are passed on to the callback. Parsing headers is very -easy using this. \fIbuffer\fP points to the delivered data, and the size of -that data is \fInitems\fP; \fIsize\fP is always 1. Do not assume that the -header line is null-terminated! +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. Do not assume that +the header line is null-terminated! The pointer named \fIuserdata\fP is the one you set with the \fICURLOPT_HEADERDATA(3)\fP option. This callback function must return the number of bytes actually taken care of. -If that amount differs from the amount passed in to your function, it'll signal +If that amount differs from the amount passed in to your function, it will signal an error to the library. This will cause the transfer to get aborted and the libcurl function in progress will return \fICURLE_WRITE_ERROR\fP. diff --git a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 index 9f1a7b43d..e472bf8ce 100644 --- a/docs/libcurl/opts/CURLOPT_HEADEROPT.3 +++ b/docs/libcurl/opts/CURLOPT_HEADEROPT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HEADEROPT 3 "October 31, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HEADEROPT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HEADEROPT \- set how to send HTTP headers +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: diff --git a/docs/libcurl/opts/CURLOPT_HSTS.3 b/docs/libcurl/opts/CURLOPT_HSTS.3 new file mode 100644 index 000000000..202db91e8 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTS.3 @@ -0,0 +1,77 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2020 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTS 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.SH NAME +CURLOPT_HSTS \- HSTS cache file name +.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 file name 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 will also enable 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 will simply start empty. Setting the file name to NULL or "" will +only enable HSTS without reading from or writing to any file. + +If this option is set multiple times, libcurl will load cache entries from +each given file but will only store 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: + +[host] [stamp] + +[host] is the domain name for the entry and the name is dot-prefixed if it is +a includeSubDomain entry (if the entry is valid for all subdmains 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 file name +.SH PROTOCOLS +HTTPS and HTTP +.SH EXAMPLE +.nf +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 7.74.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HSTS_CTRL "(3), " CURLOPT_ALTSVC "(3), " CURLOPT_RESOLVE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 new file mode 100644 index 000000000..b57e16745 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSREADDATA.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTSREADDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 will 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 feature is only used for HTTP(S) transfer. +.SH EXAMPLE +.nf +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 7.74.0 +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_HSTSREADFUNCTION "(3), " CURLOPT_HSTSWRITEDATA "(3), " +.BR CURLOPT_HSTSWRITEFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 new file mode 100644 index 000000000..9fbb567da --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSREADFUNCTION.3 @@ -0,0 +1,81 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTSREADFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.SH NAME +CURLOPT_HSTSREADFUNCTION \- read callback for HSTS hosts +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLSTScode hstsread(CURL *easy, struct curl_hstsentry *sts, void *userp); + +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 \fIuserp\fP argument with the \fICURLOPT_HSTSREADDATA(3)\fP option or +it will be NULL. + +When this callback is invoked, the \fIsts\fP pointer points to a populated +struct: Copy the host name to 'name' (no longer than 'namelen' bytes). Make it +null-terminated. Set 'includeSubDomains' to TRUE or FALSE. Set 'expire' to a +date stamp or a zero length string for *forever* (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 will stop 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 feature is only used for HTTP(S) transfer. +.SH EXAMPLE +.nf +{ + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADFUNCTION, hstsread); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSREADDATA, &hstspreload[0]); + + result = curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.74.0 +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_HSTSREADDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), " +.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), " + diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 new file mode 100644 index 000000000..295984b1d --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEDATA.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTSWRITEDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 will get as +input in the 4th 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 feature is only used for HTTP(S) transfer. +.SH EXAMPLE +.nf +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 7.74.0 +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_HSTSWRITEFUNCTION "(3), " CURLOPT_HSTSREADDATA "(3), " +.BR CURLOPT_HSTSREADFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 new file mode 100644 index 000000000..677af1899 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTSWRITEFUNCTION.3 @@ -0,0 +1,80 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTSWRITEFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.SH NAME +CURLOPT_HSTSWRITEFUNCTION \- write callback for HSTS hosts +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLSTScode hstswrite(CURL *easy, struct curl_hstsentry *sts, + struct curl_index *count, void *userp); + +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 \fIuserp\fP argument with the \fICURLOPT_HSTSWRITEDATA(3)\fP option or +it will be NULL. + +When the callback is invoked, the \fIsts\fP pointer points to a populated +struct: Read the host name to 'name' (it is 'namelen' bytes long and null +terminated. The 'includeSubDomains' field is non-zero if the entry matches +subdomains. The 'expire' 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's 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 feature is only used for HTTP(S) transfer. +.SH EXAMPLE +.nf +{ + /* set HSTS read callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEFUNCTION, hstswrite); + + /* pass in suitable argument to the callback */ + curl_easy_setopt(curl, CURLOPT_HSTSWRITEDATA, &hstspreload[0]); + + result = curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.74.0 +.SH RETURN VALUE +This will return CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_HSTSWRITEDATA "(3), " CURLOPT_HSTSWRITEFUNCTION "(3), " +.BR CURLOPT_HSTS "(3), " CURLOPT_HSTS_CTRL "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 new file mode 100644 index 000000000..594c454c5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_HSTS_CTRL.3 @@ -0,0 +1,69 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2020, 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_HSTS_CTRL 3 "September 06, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 will then automatically redirect 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. HSTS is disabled by default. +.SH PROTOCOLS +HTTPS and HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_HSTS_CTRL, CURLHSTS_ENABLE); + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Added in 7.74.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_HSTS "(3), " CURLOPT_CONNECT_TO "(3), " CURLOPT_RESOLVE "(3), " +.BR CURLOPT_ALTSVC "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 index 53718dbb5..37f61c2c4 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP09_ALLOWED.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTP09_ALLOWED 3 "August 05, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTP09_ALLOWED 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTP09 \- allow HTTP/0.9 response +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. diff --git a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 index 8c66345a1..38754d372 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP200ALIASES.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTP200ALIASES 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTP200ALIASES 3 "November 01, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTP200ALIASES \- specify alternative matches for HTTP 200 OK +CURLOPT_HTTP200ALIASES \- alternative matches for HTTP 200 OK .SH SYNOPSIS .nf #include <curl/curl.h> @@ -33,11 +33,11 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP200ALIASES, .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 very old -Icecast 1.3.x servers will respond like that for certain user agent headers or -in absence of such. By including this string in your list of aliases, -the response will be treated as a valid HTTP header line such as -"HTTP/1.0 200 OK". +example, SHOUTcast servers respond with "ICY 200 OK". Also some old Icecast +1.3.x servers will respond like that for certain user agent headers or in +absence of such. By including this string in your list of aliases, the +response will be 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 diff --git a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 index 75796957b..333e79b78 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPAUTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPAUTH 3 "June 15, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPAUTH 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try +CURLOPT_HTTPAUTH \- HTTP server authentication methods to try .SH SYNOPSIS .nf #include <curl/curl.h> @@ -99,6 +99,9 @@ it finds most secure. This is a meta symbol. OR this value together with a single specific auth value to force libcurl to probe for un-restricted 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 @@ -125,6 +128,8 @@ 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 RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.3 b/docs/libcurl/opts/CURLOPT_HTTPGET.3 index 305ce272f..dffdb25f8 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPGET 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPGET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 index f13b9d331..ac3a0aba3 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPHEADER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPHEADER 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPHEADER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTPHEADER \- set custom HTTP headers +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); +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 @@ -69,6 +72,16 @@ The most commonly replaced headers have "shortcuts" in the options There's 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 HEADERS +Setting some specific headers will cause libcurl to act differently. +.IP "Host:" +The specified host name will be 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 host name will instead be used in the ":authority" header +field and Host: will not be 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 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 diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 index 41af0236a..60419e8be 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPPOST 3 "September 02, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPPOST 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTPPOST \- specify the multipart formpost content +CURLOPT_HTTPPOST \- multipart formpost content .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 index 639f64f74..1d4809a49 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPROXYTUNNEL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTPPROXYTUNNEL 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTPPROXYTUNNEL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 index 812d7740b..59b20c95e 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_CONTENT_DECODING.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTP_CONTENT_DECODING 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTP_CONTENT_DECODING 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTP_CONTENT_DECODING \- enable/disable HTTP content decoding +CURLOPT_HTTP_CONTENT_DECODING \- HTTP content decoding control .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 index bd0a45db9..06c113b5a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_TRANSFER_DECODING.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTP_TRANSFER_DECODING 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTP_TRANSFER_DECODING 3 "October 22, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTP_TRANSFER_DECODING \- enable/disable HTTP transfer decoding +CURLOPT_HTTP_TRANSFER_DECODING \- HTTP transfer decoding control .SH SYNOPSIS .nf #include <curl/curl.h> @@ -50,7 +50,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.16.2 +Added in 7.16.2 Does not work with the hyper backend (it will always have +transfer decoding enabled). .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 index 8674519bf..e19eb66ce 100644 --- a/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 +++ b/docs/libcurl/opts/CURLOPT_HTTP_VERSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,38 +20,40 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_HTTP_VERSION 3 "September 14, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_HTTP_VERSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_HTTP_VERSION \- specify HTTP protocol version to use +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 will still prioritize to re-use an existing connection so it might then re-use a connection using a -HTTP version you haven't asked for. +HTTP version you have not asked for. .IP CURL_HTTP_VERSION_NONE -We don't care about what version the library uses. libcurl will use whatever +We do not care about what version the library uses. libcurl will use 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 will fall back to HTTP 1.1 if HTTP 2 can't be +Attempt HTTP 2 requests. libcurl will fall back to HTTP 1.1 if HTTP 2 cannot be negotiated with the server. (Added in 7.33.0) 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 will fall back to HTTP 1.1 if -HTTP 2 can't be negotiated with the HTTPS server. For clear text HTTP servers, +HTTP 2 cannot be negotiated with the HTTPS server. For clear text HTTP servers, libcurl will use 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 @@ -61,7 +63,7 @@ TLS handshake. (Added in 7.49.0) .IP CURL_HTTP_VERSION_3 (Added in 7.66.0) Setting this value will make libcurl attempt to use HTTP/3 directly to server given in the URL. Note that this cannot gracefully -downgrade to earlier HTTP version if the server doesn't support HTTP/3. +downgrade to earlier HTTP version if the server does not support HTTP/3. For more reliably upgrading to HTTP/3, set the preferred version to something lower and let the server announce its HTTP/3 support via Alt-Svc:. See diff --git a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 index d350d3021..9b498727b 100644 --- a/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 +++ b/docs/libcurl/opts/CURLOPT_IGNORE_CONTENT_LENGTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_IGNORE_CONTENT_LENGTH 3 "August 23, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_IGNORE_CONTENT_LENGTH \- ignore content length @@ -61,7 +61,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in 7.14.1. Support for FTP added in 7.46.0. +Added in 7.14.1. Support for FTP added in 7.46.0. This option is not working +for HTTP when libcurl is built to use the hyper backend. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 index f1b8291be..4ac7502e6 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE.3 +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_INFILESIZE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_INFILESIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_INFILESIZE \- set size of the input file to send off +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 diff --git a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 index def8299b7..2d687f4f3 100644 --- a/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_INFILESIZE_LARGE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_INFILESIZE_LARGE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_INFILESIZE_LARGE 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_INFILESIZE_LARGE \- set size of the input file to send off +CURLOPT_INFILESIZE_LARGE \- size of the input file to send off .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_INTERFACE.3 b/docs/libcurl/opts/CURLOPT_INTERFACE.3 index 52e73de8d..f217b8e67 100644 --- a/docs/libcurl/opts/CURLOPT_INTERFACE.3 +++ b/docs/libcurl/opts/CURLOPT_INTERFACE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_INTERFACE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_INTERFACE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * as parameter. This sets the \fIinterface\fP name to use as outgoing network interface. The name can be an interface name, an IP address, diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 index 95f695cf1..34ccb850e 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_INTERLEAVEDATA 3 "September 15, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_INTERLEAVEDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_INTERLEAVEDATA \- custom pointer passed to RTSP interleave callback +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 will be passed to \fICURLOPT_INTERLEAVEFUNCTION(3)\fP when interleaved RTP data is received. If diff --git a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 index 5f9755ca1..3bde839df 100644 --- a/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_INTERLEAVEFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_INTERLEAVEFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_INTERLEAVEFUNCTION 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_INTERLEAVEFUNCTION \- callback function for RTSP interleaved data +CURLOPT_INTERLEAVEFUNCTION \- callback for RTSP interleaved data .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 index d05b4add0..5560f2eed 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 +++ b/docs/libcurl/opts/CURLOPT_IOCTLDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_IOCTLDATA 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_IOCTLDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_IOCTLDATA \- custom pointer passed to I/O callback +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 will be untouched by libcurl and passed as the 3rd argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 index ba5606c54..c2528da8b 100644 --- a/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_IOCTLFUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_IOCTLFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_IOCTLFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_IOCTLFUNCTION \- callback for I/O operations @@ -49,7 +49,7 @@ 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 can't do by itself. For now, +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. diff --git a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 index 9516852c8..d568522be 100644 --- a/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_IPRESOLVE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,24 +20,27 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_IPRESOLVE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_IPRESOLVE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_IPRESOLVE \- specify which IP protocol version to use +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 -resolving host names. This is only interesting when using host names that -resolve addresses using more than one version of IP. The allowed values are: +establishing a connection or choosing one from the connection pool. This is +interesting when using host names that resolve addresses using more than +one version of IP. The allowed values are: .IP CURL_IPRESOLVE_WHATEVER -Default, resolves addresses to all IP versions that your system allows. +Default, can use addresses of all IP versions that your system allows. .IP CURL_IPRESOLVE_V4 -Resolve to IPv4 addresses. +Uses only IPv4 addresses. .IP CURL_IPRESOLVE_V6 -Resolve to IPv6 addresses. +Uses only IPv6 addresses. .SH DEFAULT CURL_IPRESOLVE_WHATEVER .SH PROTOCOLS @@ -48,7 +51,7 @@ CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin"); - /* resolve host name using IPv6-names only */ + /* of all addresses example.com resolves to, only IPv6 ones are used */ curl_easy_setopt(curl, CURLOPT_IPRESOLVE, CURL_IPRESOLVE_V6); ret = curl_easy_perform(curl); diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 b/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 index 7abe206c4..5eff62869 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ISSUERCERT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_ISSUERCERT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * 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 diff --git a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 index 5fbf86df4..06954799c 100644 --- a/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_ISSUERCERT_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,13 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_ISSUERCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_ISSUERCERT_BLOB 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .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); +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 @@ -70,7 +74,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL backends. .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 index 46e4f01f4..8d37e291f 100644 --- a/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 +++ b/docs/libcurl/opts/CURLOPT_KEEP_SENDING_ON_ERROR.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_KEEP_SENDING_ON_ERROR 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 index d8c27d09d..28e30f771 100644 --- a/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 +++ b/docs/libcurl/opts/CURLOPT_KEYPASSWD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_KEYPASSWD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_KEYPASSWD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_KEYPASSWD \- set passphrase to private key +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 will be used as the password required to use the \fICURLOPT_SSLKEY(3)\fP or diff --git a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 index ac8497d4a..b6af0aa52 100644 --- a/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 +++ b/docs/libcurl/opts/CURLOPT_KRBLEVEL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_KRBLEVEL 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_KRBLEVEL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_KRBLEVEL \- set FTP kerberos security level +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 * 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: \&'clear', \&'safe', \&'confidential' or \&'private'. If the -string is set but doesn't match one of these, 'private' will be used. Set the +string is set but does not match one of these, 'private' will be 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 diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORT.3 b/docs/libcurl/opts/CURLOPT_LOCALPORT.3 index 18e08014a..238acf92a 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORT.3 +++ b/docs/libcurl/opts/CURLOPT_LOCALPORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_LOCALPORT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_LOCALPORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_LOCALPORT \- set local port number to use for socket +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 diff --git a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 index 63a2f1962..6d1505323 100644 --- a/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 +++ b/docs/libcurl/opts/CURLOPT_LOCALPORTRANGE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_LOCALPORTRANGE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_LOCALPORTRANGE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will make to find a working local port number. It starts with the given diff --git a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 index 6b593f4f0..3d1a9ee73 100644 --- a/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_LOGIN_OPTIONS 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_LOGIN_OPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_LOGIN_OPTIONS \- set login options +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 * as parameter, which should be pointing to the null-terminated \fIoptions\fP string to use for the transfer. diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 index f29df3ace..aa58b2d85 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_LIMIT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_LOW_SPEED_LIMIT 3 "May 06, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_LOW_SPEED_LIMIT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_LOW_SPEED_LIMIT \- set low speed limit in bytes per second +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); +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 diff --git a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 index 2696e5426..029598245 100644 --- a/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 +++ b/docs/libcurl/opts/CURLOPT_LOW_SPEED_TIME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_LOW_SPEED_TIME 3 "May 06, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_LOW_SPEED_TIME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_LOW_SPEED_TIME \- set low speed limit time period +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); +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 diff --git a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 index 61ce76c65..357d89b86 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_AUTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAIL_AUTH 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAIL_AUTH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will be used to specify the authentication address (identity) of a submitted message that is diff --git a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 index f707022c4..bfcdffbf1 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_FROM.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAIL_FROM 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAIL_FROM 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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's email address when sending SMTP mail with libcurl. diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 index cc6026b65..6aa8a2cbc 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAIL_RCPT 3 "July 16, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAIL_RCPT 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_MAIL_RCPT \- list of SMTP mail recipients diff --git a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLLOWFAILS.3 b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLLOWFAILS.3 index 996619177..81557e2f8 100644 --- a/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLLOWFAILS.3 +++ b/docs/libcurl/opts/CURLOPT_MAIL_RCPT_ALLLOWFAILS.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAIL_RCPT_ALLLOWFAILS 3 "January 14, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAIL_RCPT_ALLLOWFAILS 3 "July 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_MAIL_RCPT_ALLLOWFAILS \- allow RCPT TO command to fail for some recipients @@ -40,8 +40,9 @@ return an error. The default behavior can be changed by setting \fIignore\fP to 1L which will make curl ignore errors and proceed with the remaining valid recipients. -In case when all recipients cause RCPT TO command to fail, curl will abort SMTP -conversation and return the error received from to the last RCPT TO command. +If all recipients trigger RCPT TO failures and this flag is specified, curl +will still abort the SMTP conversation and return the error received from to +the last RCPT TO command. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 index d36767bf6..81404aae8 100644 --- a/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 +++ b/docs/libcurl/opts/CURLOPT_MAXAGE_CONN.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 2019 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,23 +20,25 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAXAGE_CONN 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAXAGE_CONN 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 maxage); +.fi .SH DESCRIPTION Pass a long as parameter containing \fImaxage\fP - the maximum time in seconds -that you allow an existing connection to have to be considered for reuse for -this request. +that you allow an existing connection to have been idle to be considered for +reuse for this request. The "connection cache" that holds previously used connections. When a new request is to be done, it will consider any connection that matches for -reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying -very old connections for reuse, since old connections have a high risk of not +reuse. The \fICURLOPT_MAXAGE_CONN(3)\fP limit prevents libcurl from trying too +old connections for reuse, since old connections have a high 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 \fImaxage\fP, it will instead be @@ -58,9 +60,9 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.65.0 +Added in 7.65.0 .SH RETURN VALUE Returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_TIMEOUT "(3), " CURLOPT_FORBID_REUSE "(3), " -.BR CURLOPT_FRESH_CONNECT "(3), " +.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXLIFETIME_CONN "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 index 85821f5bf..92d4b43aa 100644 --- a/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 +++ b/docs/libcurl/opts/CURLOPT_MAXCONNECTS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAXCONNECTS 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAXCONNECTS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will be the maximum number of simultaneously open persistent connections that libcurl may cache in the pool associated with -this handle. The default is 5, and there isn't much point in changing this +this handle. The default is 5, and there is not much point in changing this value unless you are perfectly aware of how this works and changes libcurl's -behaviour. This concerns connections using any of the protocols that support +behavior. This concerns connections using any of the protocols that support persistent connections. When reaching the maximum limit, curl closes the oldest one in the cache to diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 index ab2ae4eab..37a2201df 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAXFILESIZE 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAXFILESIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 allows you to specify the maximum \fIsize\fP (in bytes) of a file to download. If the file requested is found larger than @@ -36,13 +38,13 @@ be returned. The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this -given limit. This concerns both FTP and HTTP transfers. +given limit. If you want a limit above 2GB, use \fICURLOPT_MAXFILESIZE_LARGE(3)\fP. .SH DEFAULT None .SH PROTOCOLS -FTP and HTTP +FTP, HTTP and MQTT .SH EXAMPLE .nf CURL *curl = curl_easy_init(); diff --git a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 index f4166e062..fda432e9c 100644 --- a/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAXFILESIZE_LARGE.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAXFILESIZE_LARGE 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAXFILESIZE_LARGE 3 "July 23, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_MAXFILESIZE_LARGE \- maximum file size allowed to download @@ -38,11 +38,11 @@ larger than this value, the transfer will not start and The file size is not always known prior to download, and for such files this option has no effect even if the file transfer ends up being larger than this -given limit. This concerns both FTP and HTTP transfers. +given limit. .SH DEFAULT None .SH PROTOCOLS -FTP and HTTP +FTP, HTTP and MQTT .SH EXAMPLE .nf CURL *curl = curl_easy_init(); diff --git a/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 new file mode 100644 index 000000000..d1e28bdf5 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MAXLIFETIME_CONN.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_MAXLIFETIME_CONN 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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, it will consider 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 will instead be closed once any in-progress transfers +complete. + +If set to 0, this behavior is disabled: all connections are eligible for reuse. +.SH DEFAULT +Default \fImaxlifetime\fP is 0 seconds (i.e., disabled). +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +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 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK. +.SH "SEE ALSO" +.BR CURLOPT_TIMEOUT "(3), " CURLOPT_FORBID_REUSE "(3), " +.BR CURLOPT_FRESH_CONNECT "(3), " CURLOPT_MAXAGE_CONN "(3), " diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 index ec0267952..a99362bac 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAXREDIRS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAXREDIRS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will be the redirection limit \fIamount\fP. If that many redirections have been followed, the next redirect will cause an diff --git a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 index 264a40d4d..965211ab8 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAX_RECV_SPEED_LARGE.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "August 14, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAX_RECV_SPEED_LARGE 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_MAX_RECV_SPEED_LARGE \- rate limit data download speed @@ -41,7 +41,7 @@ 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 doesn't affect transfer speeds done with FILE:// URLs. +This option does not affect transfer speeds done with FILE:// URLs. .SH DEFAULT 0, disabled .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 index 31e0db064..292f5444a 100644 --- a/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_MAX_SEND_SPEED_LARGE.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "August 14, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MAX_SEND_SPEED_LARGE 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_MAX_SEND_SPEED_LARGE \- rate limit data upload speed @@ -43,7 +43,7 @@ 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 doesn't affect transfer speeds done with FILE:// URLs. +This option does not affect transfer speeds done with FILE:// URLs. .SH DEFAULT 0, disabled .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 index 79d7b8bac..3e101b95e 100644 --- a/docs/libcurl/opts/CURLOPT_MIMEPOST.3 +++ b/docs/libcurl/opts/CURLOPT_MIMEPOST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_MIMEPOST 3 "September 04, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_MIMEPOST 3 "December 17, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_MIMEPOST \- set post/send data from mime structure +CURLOPT_MIMEPOST \- send data from mime structure .SH SYNOPSIS .nf #include <curl/curl.h> @@ -35,19 +35,19 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MIMEPOST, mime); 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 e-mail data to send/upload. +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 deprecated \fICURLOPT_HTTPPOST(3)\fP option. .SH PROTOCOLS HTTP, SMTP, IMAP. -.SH AVAILABILITY -Since 7.56.0. -.SH RETURN VALUE -This will return CURLE_OK. .SH EXAMPLE Using this option implies the use of several mime structure building -functions: see https://curl.haxx.se/libcurl/c/smtp-mime.html for a complete +functions: see https://curl.se/libcurl/c/smtp-mime.html for a complete example. +.SH AVAILABILITY +Added in 7.56.0 +.SH RETURN VALUE +This will return CURLE_OK. .SH "SEE ALSO" .BR curl_mime_init "(3)" diff --git a/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 new file mode 100644 index 000000000..9d2b725af --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_MIME_OPTIONS.3 @@ -0,0 +1,92 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_MIME_OPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 CURLMIMEOPT_* defines. 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 file names 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 to address +server-side applications that have not yet have been converted. + +As an example, consider field or file name \fIstrange\\name"kind\fP. +When the containing multipart form is sent, this is normally transmitted as +\fIstrange\\name%22kind\fP. When this option is set, it is sent as +\fIstrange\\\\name\\"kind\fP. +.SH DEFAULT +0, meaning disabled. +.SH PROTOCOLS +HTTP, IMAP, SMTP +.SH EXAMPLE +.nf +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, 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(mime); +} +.fi +.SH AVAILABILITY +Option added in 7.81.0. +.SH RETURN VALUE +Returns CURLE_OK +.SH "SEE ALSO" +.BR CURLOPT_MIMEPOST "(3), " CURLOPT_HTTPPOST "(3)" diff --git a/docs/libcurl/opts/CURLOPT_NETRC.3 b/docs/libcurl/opts/CURLOPT_NETRC.3 index 2e9476b0b..f27c8b921 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC.3 +++ b/docs/libcurl/opts/CURLOPT_NETRC.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NETRC 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NETRC 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_NETRC \- request that .netrc is used +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 user names and passwords from your \fI~/.netrc\fP file, relative to user names @@ -40,7 +42,7 @@ libcurl uses a user name (and supplied or prompted password) supplied with the options controlled by this parameter. Only machine name, user name and password are taken into account (init macros -and similar things aren't supported). +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. diff --git a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 index 544a76702..b5d2b0cca 100644 --- a/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 +++ b/docs/libcurl/opts/CURLOPT_NETRC_FILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2017, 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NETRC_FILE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NETRC_FILE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_NETRC_FILE \- file name 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 * as parameter, pointing to a null-terminated string containing the full path name to the \fIfile\fP you want libcurl to use as .netrc diff --git a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 index 89db0bc0b..81fd272c3 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 +++ b/docs/libcurl/opts/CURLOPT_NEW_DIRECTORY_PERMS.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NEW_DIRECTORY_PERMS 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NEW_DIRECTORY_PERMS 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_NEW_DIRECTORY_PERMS \- permissions for remotely created directories diff --git a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 index d22de64e0..be86774b8 100644 --- a/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 +++ b/docs/libcurl/opts/CURLOPT_NEW_FILE_PERMS.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NEW_FILE_PERMS 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NEW_FILE_PERMS 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_NEW_FILE_PERMS \- permissions for remotely created files diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 index e87b17a43..762ac305d 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.3 +++ b/docs/libcurl/opts/CURLOPT_NOBODY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NOBODY 3 "July 27, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NOBODY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 @@ -37,7 +39,7 @@ to transfer the body data. For HTTP operations when \fICURLOPT_NOBODY(3)\fP has been set, unsetting the option (with 0) will make 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 ur UPLOAD +\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. diff --git a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 index 13512ecd2..83db6f102 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 +++ b/docs/libcurl/opts/CURLOPT_NOPROGRESS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NOPROGRESS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NOPROGRESS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will also prevent the diff --git a/docs/libcurl/opts/CURLOPT_NOPROXY.3 b/docs/libcurl/opts/CURLOPT_NOPROXY.3 index 597468e16..ceab2d55a 100644 --- a/docs/libcurl/opts/CURLOPT_NOPROXY.3 +++ b/docs/libcurl/opts/CURLOPT_NOPROXY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NOPROXY 3 "August 22, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NOPROXY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 host names that do not require a proxy to get reached, even @@ -51,7 +53,7 @@ brackets: "example.com,::1,localhost" IPv6 numerical addresses are compared as strings, so they will only match if -the representations are the same: "::1" is the same as "::0:1" but they don't +the representations are the same: "::1" is the same as "::0:1" but they do not match. The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 index 466273de0..cfd4150af 100644 --- a/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 +++ b/docs/libcurl/opts/CURLOPT_NOSIGNAL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_NOSIGNAL 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_NOSIGNAL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 will not use any functions that install signal handlers or any functions that cause signals to be sent to the process. This @@ -50,7 +52,24 @@ cases when they may still happen, contrary to our desire. In addition, using raised. .SH DEFAULT 0 +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); + + curl_easy_setopt(curl, CURLOPT_NOSIGNAL, 1L); + + ret = curl_easy_perform(curl); + + curl_easy_cleanup(curl); +} +.fi .SH AVAILABILITY Added in 7.10 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TIMEOUT "(3), " diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 index 10beb2c56..1a1089de8 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_OPENSOCKETDATA 3 "May 15, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_OPENSOCKETDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_OPENSOCKETDATA \- custom pointer passed to open socket callback +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 will be untouched by libcurl and passed as the first argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 index 0f88f19ad..45739c2db 100644 --- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_OPENSOCKETFUNCTION 3 "June 09, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_OPENSOCKETFUNCTION 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_OPENSOCKETFUNCTION \- set callback for opening sockets +CURLOPT_OPENSOCKETFUNCTION \- callback for opening socket .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_PASSWORD.3 index eff48dc96..8a29c479b 100644 --- a/docs/libcurl/opts/CURLOPT_PASSWORD.3 +++ b/docs/libcurl/opts/CURLOPT_PASSWORD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PASSWORD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PASSWORD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * as parameter, which should be pointing to the null-terminated password to use for the transfer. diff --git a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 index 8d8ca0d7f..7c51a710f 100644 --- a/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 +++ b/docs/libcurl/opts/CURLOPT_PATH_AS_IS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PATH_AS_IS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PATH_AS_IS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 index 21ed6e9e7..cfb7bbe6b 100644 --- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PINNEDPUBLICKEY 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PINNEDPUBLICKEY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PINNEDPUBLICKEY \- set pinned public key +CURLOPT_PINNEDPUBLICKEY \- pinned public key .SH SYNOPSIS +.nf #include <curl/curl.h> -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY, char *pinnedpubkey); +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 file name of your pinned public key. The file format expected is "PEM" or "DER". @@ -65,14 +68,14 @@ if(curl) { If you do not have the server's public key file you can extract it from the server's certificate. .nf -# retrieve the server's certificate if you don't already have it +# 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 don't have sed, then just copy the certificate into a file: +# - 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 diff --git a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 index 32fcdb5a7..6fefb20e1 100644 --- a/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 +++ b/docs/libcurl/opts/CURLOPT_PIPEWAIT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PIPEWAIT 3 "May 01, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PIPEWAIT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PIPEWAIT \- wait for pipelining/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 pipelining or multiplexing before continuing. @@ -55,6 +57,15 @@ and support level. .SH PROTOCOLS HTTP(S) .SH EXAMPLE +.nf +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 7.43.0 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PORT.3 b/docs/libcurl/opts/CURLOPT_PORT.3 index c50828d62..7c28730fe 100644 --- a/docs/libcurl/opts/CURLOPT_PORT.3 +++ b/docs/libcurl/opts/CURLOPT_PORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PORT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PORT \- set remote port number to work with +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 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 diff --git a/docs/libcurl/opts/CURLOPT_POST.3 b/docs/libcurl/opts/CURLOPT_POST.3 index e43203b87..06304c592 100644 --- a/docs/libcurl/opts/CURLOPT_POST.3 +++ b/docs/libcurl/opts/CURLOPT_POST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POST 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_POST \- request an HTTP POST +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 will also make the library use a "Content-Type: application/x-www-form-urlencoded" diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 index 672722201..c774432fe 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POSTFIELDS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POSTFIELDS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_POSTFIELDS \- specify data to POST to server +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 * as parameter, pointing to the full data to send in an HTTP POST operation. You must make sure that the data is formatted the way you want the @@ -36,7 +38,7 @@ way. For example, the 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 behaviour can be changed (so libcurl does copy the data) by setting the +This behavior can be changed (so libcurl does copy the data) by setting the \fICURLOPT_COPYPOSTFIELDS(3)\fP option. This POST is a normal application/x-www-form-urlencoded kind (and libcurl will @@ -53,6 +55,11 @@ the POST data from the read callback. If you want to send a zero-byte 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 will use assume this option points to a nul-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 nul +bytes included in the data. + Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, and libcurl will add 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 diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 index c3ea8c92e..170e42b4b 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POSTFIELDSIZE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POSTFIELDSIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 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 diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 index d330c25dc..53a3e32aa 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POSTFIELDSIZE_LARGE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POSTFIELDSIZE_LARGE 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_POSTFIELDSIZE_LARGE \- size of POST data pointed to diff --git a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 index 9d1f433ad..d2e9cba84 100644 --- a/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTQUOTE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POSTQUOTE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POSTQUOTE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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 will only be run if no error diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 index 6ee062045..62f4593ed 100644 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_POSTREDIR 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_POSTREDIR 3 "December 31, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_POSTREDIR \- how to act on an HTTP POST redirect @@ -41,7 +41,7 @@ libcurl maintain the request method after a 302 redirect whilst setting bit 2 after a 303 redirect. The value \fBCURL_REDIR_POST_ALL\fP is a convenience define that sets all three bits. -The non-RFC behaviour is ubiquitous in web browsers, so the library does the +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. diff --git a/docs/libcurl/opts/CURLOPT_PREQUOTE.3 b/docs/libcurl/opts/CURLOPT_PREQUOTE.3 index 959fbbbf3..133076fb1 100644 --- a/docs/libcurl/opts/CURLOPT_PREQUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_PREQUOTE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PREQUOTE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PREQUOTE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_PREREQDATA.3 b/docs/libcurl/opts/CURLOPT_PREREQDATA.3 new file mode 100644 index 000000000..82f249cac --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PREREQDATA.3 @@ -0,0 +1,64 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2021, Max Dymond, <max.dymond@microsoft.com>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_PREREQDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 will be 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 +All +.SH EXAMPLE +.nf +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:%s\\n", conn_primary_ip, conn_primary_port); + return CURL_PREREQFUNC_OK; +} + +{ + struct data prereq_data; + curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback); + curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data); +} +.fi +.SH AVAILABILITY +Added in 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_PREREQFUNCTION "(3) " diff --git a/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 new file mode 100644 index 000000000..e2c460232 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PREREQFUNCTION.3 @@ -0,0 +1,105 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 2021, Max Dymond, <max.dymond@microsoft.com>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_PREREQFUNCTION 3 "November 04, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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); +.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). + +This function is passed the following information: +.IP conn_primary_ip +A nul-terminated pointer to a 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 nul-terminated pointer to a 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 dependending on the protocol. +.IP conn_local_port +The originating port number for this connection. This can be a TCP or a UDP port +number dependending on the protocol. +.RE + +\fIclientp\fP is the pointer you set with \fICURLOPT_PREREQDATA(3)\fP. + +The callback function must return \fICURL_PREREQFUNC_OK\fP on success, or +\fICURL_PREREQFUNC_ABORT\fP to cause the transfer to fail. + +.SH DEFAULT +By default, this is NULL and unused. +.SH PROTOCOLS +ALL +.SH EXAMPLE +.nf +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:%s\\n", conn_primary_ip, conn_primary_port); + return CURL_PREREQFUNC_OK; +} + +{ + struct data prereq_data; + curl_easy_setopt(CURL *handle, CURLOPT_PREREQFUNCTION, prereq_callback); + curl_easy_setopt(CURL *handle, CURLOPT_PREREQDATA, &prereq_data); +} +.fi +.SH AVAILABILITY +Added in 7.80.0 +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH "SEE ALSO" +.BR CURLOPT_PREREQDATA "(3) " diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 index c53556585..5f6c0dcab 100644 --- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PRE_PROXY 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PRE_PROXY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PRE_PROXY \- set pre-proxy to use +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 host name or dotted @@ -60,7 +62,7 @@ Default is NULL, meaning no pre proxy is used. When you set a host name to use, do not assume that there's any particular single port number used widely for proxies. Specify it! .SH PROTOCOLS -All except file://. Note that some protocols don't do very well over proxy. +All except file://. Note that some protocols do not work well over proxy. .SH EXAMPLE .nf CURL *curl = curl_easy_init(); diff --git a/docs/libcurl/opts/CURLOPT_PRIVATE.3 b/docs/libcurl/opts/CURLOPT_PRIVATE.3 index e8144574c..8a6e16594 100644 --- a/docs/libcurl/opts/CURLOPT_PRIVATE.3 +++ b/docs/libcurl/opts/CURLOPT_PRIVATE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PRIVATE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PRIVATE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 index 1ff69e22d..fcd01d05b 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROGRESSDATA 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROGRESSDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROGRESSDATA \- custom pointer passed to the progress callback +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 will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION(3)\fP. @@ -36,7 +38,32 @@ The default value of this parameter is NULL. .SH PROTOCOLS All .SH EXAMPLE -https://curl.haxx.se/libcurl/c/progressfunc.html +.nf + struct progress { + char *private; + size_t size; + }; + + static size_t progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow) + { + struct memory *progress = (struct progress *)userp; + + /* use the values */ + + return 0; /* all is good */ + } + + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data); + + curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback); +.fi .SH AVAILABILITY Always .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 index 9d3387877..09e4526e3 100644 --- a/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_PROGRESSFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,11 +20,12 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROGRESSFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROGRESSFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROGRESSFUNCTION \- callback to progress meter function +CURLOPT_PROGRESSFUNCTION \- progress meter callback .SH SYNOPSIS +.nf #include <curl/curl.h> int progress_callback(void *clientp, @@ -33,7 +34,9 @@ int progress_callback(void *clientp, double ultotal, double ulnow); -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROGRESSFUNCTION, progress_callback); +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. @@ -42,7 +45,7 @@ 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 will be called very +frequent interval. While data is being transferred it will be called frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. @@ -74,12 +77,37 @@ function that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. .SH DEFAULT -By default, libcurl has an internal progress meter. That's rarely wanted by +By default, libcurl has an internal progress meter. That is rarely wanted by users. .SH PROTOCOLS All .SH EXAMPLE -https://curl.haxx.se/libcurl/c/progressfunc.html +.nf + struct progress { + char *private; + size_t size; + }; + + static size_t progress_callback(void *clientp, + double dltotal, + double dlnow, + double ultotal, + double ulnow) + { + struct memory *progress = (struct progress *)userp; + + /* use the values */ + + return 0; /* all is good */ + } + + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl_handle, CURLOPT_PROGRESSDATA, &data); + + curl_easy_setopt(curl_handle, CURLOPT_PROGRESSFUNCTION, progress_callback); +.fi .SH AVAILABILITY Always .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 index 2f3e8c5ee..de9f2d9df 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROTOCOLS 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROTOCOLS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROTOCOLS \- set allowed protocols +CURLOPT_PROTOCOLS \- allowed protocols .SH SYNOPSIS +.nf #include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROTOCOLS, long bitmask); +.fi .SH DESCRIPTION Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3 index 9f1c45b12..0b58a1f82 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY \- set proxy to use +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 the upcoming request. The parameter should be a char * to a null-terminated string holding the host name or dotted numerical @@ -62,7 +64,7 @@ which kind of proxy the string identifies. When you tell the library to use an HTTP proxy, libcurl will transparently convert 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 don't work unless you +\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. @@ -91,7 +93,7 @@ Default is NULL, meaning no proxy is used. When you set a host name to use, do not assume that there's any particular single port number used widely for proxies. Specify it! .SH PROTOCOLS -All except file://. Note that some protocols don't do very well over proxy. +All except file://. Note that some protocols do not work well over proxy. .SH EXAMPLE .nf CURL *curl = curl_easy_init(); diff --git a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 index cf3c083ca..e6f54777d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYAUTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYAUTH 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYAUTH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXYAUTH \- set HTTP proxy authentication methods to try +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 diff --git a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 index a1b9aaa82..9c0a2991d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYHEADER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYHEADER 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYHEADER 3 "November 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXYHEADER \- custom HTTP headers to pass to proxy +CURLOPT_PROXYHEADER \- set of HTTP headers to pass to proxy .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 index 49a7c31ca..373cea50e 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYPASSWORD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYPASSWORD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYPASSWORD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * as parameter, which should be pointing to the null-terminated password to use for authentication with the proxy. diff --git a/docs/libcurl/opts/CURLOPT_PROXYPORT.3 b/docs/libcurl/opts/CURLOPT_PROXYPORT.3 index d72fd0a1f..4ca2a002f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYPORT.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYPORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYPORT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYPORT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 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. -While this accepts a 'long', the port number is 16 bit so it can't be larger +While this accepts a 'long', the port number is 16 bit so it cannot be larger than 65535. .SH DEFAULT 0, not specified which makes it use the default port diff --git a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 index 14d360345..8d5b7bce8 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYTYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYTYPE 3 "May 30, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYTYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. @@ -37,9 +39,9 @@ HTTP Proxy. Default. .IP CURLPROXY_HTTPS HTTPS Proxy. (Added in 7.52.0 for OpenSSL, GnuTLS and NSS) .IP CURLPROXY_HTTP_1_0 -HTTP 1.0 Proxy. This is very similar to CURLPROXY_HTTP except it uses HTTP/1.0 -for any CONNECT tunnelling. It does not change the HTTP version of the actual -HTTP requests, controlled by \fICURLOPT_HTTP_VERSION(3)\fP. +HTTP 1.0 Proxy. This is similar to CURLPROXY_HTTP except it uses HTTP/1.0 for +any CONNECT tunnelling. 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 diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 index 55b8ac499..36d68bcf9 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERNAME.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYUSERNAME 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYUSERNAME 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PROXYUSERNAME \- user name to use for proxy authentication diff --git a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 index 868fcfa1d..37b7a645c 100644 --- a/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXYUSERPWD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXYUSERPWD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXYUSERPWD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PROXYUSERPWD \- user name 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 * as parameter, which should be [user name]:[password] to use for the connection to the HTTP proxy. Both the name and the password will be URL diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 index e838f86ed..b1c14d548 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_CAINFO 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_CAINFO 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. @@ -71,14 +73,15 @@ if(curl) { .SH AVAILABILITY Added in 7.52.0 -For TLS backends that don't support certificate files, the +For TLS backends that do not support certificate files, the \fICURLOPT_PROXY_CAINFO(3)\fP option is ignored. Refer to -https://curl.haxx.se/docs/ssl-compared.html +https://curl.se/docs/ssl-compared.html .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. .SH "SEE ALSO" -.BR CURLOPT_PROXY_CAPATH "(3), " +.BR CURLOPT_PROXY_CAINFO_BLOB "(3), " CURLOPT_PROXY_CAPATH "(3), " .BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), " +.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), " .BR CURLOPT_CAPATH "(3), " .BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 new file mode 100644 index 000000000..92072fa5e --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAINFO_BLOB.3 @@ -0,0 +1,79 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_PROXY_CAINFO_BLOB 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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 \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP is zero and you avoid verifying the +server's certificate, \fICURLOPT_PROXY_CAINFO_BLOB(3)\fP is not needed. + +This option overrides \fICURLOPT_PROXY_CAINFO(3)\fP. +.SH DEFAULT +NULL +.SH PROTOCOLS +Used with HTTPS proxy +.SH EXAMPLE +.nf +char *strpem; /* strpem must point to a PEM string */ +CURL *curl = curl_easy_init(); +if(curl) { + 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); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in 7.77.0. + +This option is supported by the OpenSSL, Secure +Transport and Schannel backends. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_PROXY_CAINFO "(3), " CURLOPT_PROXY_CAPATH "(3), " +.BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " CURLOPT_PROXY_SSL_VERIFYHOST "(3), " +.BR CURLOPT_CAINFO "(3), " CURLOPT_CAINFO_BLOB "(3), " +.BR CURLOPT_CAPATH "(3), " +.BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_SSL_VERIFYHOST "(3), " diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 index 6b36f72f9..a2dc78947 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CAPATH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_CAPATH 3 "August 24, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_CAPATH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_CAPATH \- specify directory holding proxy CA certificates +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 * to a null-terminated string naming a directory holding multiple CA certificates to verify the HTTPS proxy with. If libcurl is built against diff --git a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 index 5465fa281..ec26015db 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_CRLFILE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_CRLFILE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_CRLFILE \- specify a proxy Certificate Revocation List file +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 index 821ebe770..55cb108fc 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_ISSUERCERT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_ISSUERCERT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * 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 @@ -65,7 +67,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL backends. .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 index 857fffde9..a6ac8af48 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,9 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_ISSUERCERT_BLOB 3 "November 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .SH NAME -CURLOPT_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob +CURLOPT_PROXY_ISSUERCERT_BLOB \- proxy issuer SSL certificate from memory blob .SH SYNOPSIS .nf #include <curl/curl.h> @@ -76,7 +77,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL backends. .SH RETURN VALUE Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 index 29128d4db..5cff8fcf4 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_KEYPASSWD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_KEYPASSWD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_KEYPASSWD \- set passphrase to proxy private key +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 index 2b3eac526..23a690c7a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_PINNEDPUBLICKEY \- set pinned public key for https proxy +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 file name of your pinned public key. The file format expected is "PEM" or "DER". @@ -64,14 +66,14 @@ if(curl) { If you do not have the https proxy server's public key file you can extract it from the https proxy server's certificate. .nf -# retrieve the server's certificate if you don't already have it +# 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 don't have sed, then just copy the certificate into a file: +# - 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 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 index 2850258fc..fc2d59116 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SERVICE_NAME 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SERVICE_NAME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SERVICE_NAME, + char *name); +.fi .SH DESCRIPTION Pass a char * as parameter to a string holding the \fIname\fP of the service. The default service name is "HTTP" for HTTP based proxies and "rcmd" diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 index 1bfb8e863..e72fade2f 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLCERT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLCERT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLCERT \- set SSL proxy client certificate +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 index 917c02647..76753e2b1 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLCERTTYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLCERTTYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLCERTTYPE \- specify type of the proxy client SSL certificate +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 index 8b5a1336d..19ee25747 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLCERT_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,13 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLCERT_BLOB 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .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); +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 @@ -62,8 +66,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL, Secure -Transport and Schannel backends. +Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and +Schannel backends. .SH RETURN VALUE Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 index 4cc4bcde9..bef93b175 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLKEY 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLKEY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLKEY \- specify private keyfile for TLS and SSL proxy client cert +CURLOPT_PROXY_SSLKEY \- private keyfile 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 file name of your private key used for connecting to the HTTPS proxy. The diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 index e1c615f61..3120de862 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLKEYTYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLKEYTYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLKEYTYPE \- set type of the proxy private key file +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 index daaff0df0..e449be1b7 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLKEY_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,8 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLKEY_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLKEY_BLOB 3 "October 25, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .SH NAME CURLOPT_PROXY_SSLKEY_BLOB \- private key for proxy cert from memory blob .SH SYNOPSIS @@ -65,7 +66,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL backends. .SH RETURN VALUE Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 index f436be5d4..ed627e23b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSLVERSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSLVERSION 3 "October 31, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSLVERSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSLVERSION \- set preferred proxy TLS/SSL version +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); +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. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 index 626a782c1..e4cbce48d 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSL_CIPHER_LIST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSL_CIPHER_LIST \- specify ciphers to use for proxy TLS +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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_CIPHER_LIST, + char *list); +.fi .SH DESCRIPTION Pass a char *, pointing to a null-terminated string holding the list of ciphers to use for the connection to the HTTPS proxy. The list must be @@ -35,22 +38,21 @@ syntactically correct, it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, \&!, \&- and \&+ can be used as operators. -For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', -\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you -compile OpenSSL. - -You'll find more details about cipher lists on this URL: +For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP, +\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally +set when you compile OpenSSL. - https://www.openssl.org/docs/apps/ciphers.html - -For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', -\'rsa_aes_128_sha\', etc. With NSS you don't add/remove ciphers. If one uses +For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP, +\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled. -You'll find more details about the NSS cipher lists on this URL: +For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP, +\fBAES256-SHA:AES256-SHA256\fP, etc. + +you will find more details about cipher lists on this URL: - http://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives + https://curl.se/docs/ssl-ciphers.html The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 index 0a6bbf0cf..d952200fb 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_OPTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,23 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSL_OPTIONS 3 "July 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSL_OPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_SSL_OPTIONS \- set proxy SSL behavior options +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); +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 isn't used or this bit is set to 0, +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 @@ -43,26 +46,31 @@ supported for Secure Transport, NSS and OpenSSL. 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' -Untrusted Publishers block list which it seems can't be bypassed. (Added in +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 will fail 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_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 All TLS-based protocols -.SH AVAILABLE -Added in 7.52.0 .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -76,6 +84,8 @@ if(curl) { curl_easy_cleanup(curl); } .fi +.SH AVAILABILITY +Added in 7.52.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 index e3bc216b4..72f661d07 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYHOST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "August 20, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSL_VERIFYHOST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PROXY_SSL_VERIFYHOST \- verify the proxy certificate's name against host .SH SYNOPSIS +.nf #include <curl/curl.h> -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYHOST, long verify); +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's certificate name fields against the proxy name. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 index ec54366f5..c4a446ef8 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_SSL_VERIFYPEER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "December 16, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_SSL_VERIFYPEER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PROXY_SSL_VERIFYPEER \- verify the proxy's SSL certificate .SH SYNOPSIS +.nf #include <curl/curl.h> -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_SSL_VERIFYPEER, long verify); +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 verifies the authenticity of the HTTPS proxy's -certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. +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's used for +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 @@ -53,7 +56,7 @@ 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 host name in the certificate is valid for the host name you're +that the host name in the certificate is valid for the host name you are connecting to is done independently of the \fICURLOPT_PROXY_SSL_VERIFYPEER(3)\fP option. diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 index c86235988..b1b95e45b 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,23 +20,26 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_TLS13_CIPHERS 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_TLS13_CIPHERS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLS13_CIPHERS, + char *list); +.fi .SH DESCRIPTION Pass a char *, 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. -You'll find more details about cipher lists on this URL: +you will find more details about cipher lists on this URL: - https://curl.haxx.se/docs/ssl-ciphers.html + https://curl.se/docs/ssl-ciphers.html This option is currently used only when curl is built to use OpenSSL 1.1.1 or later. If you are using a different SSL backend you can try setting TLS 1.3 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 index 4f318d52a..61772b81a 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_TLSAUTH_PASSWORD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_PASSWORD, + char *pwd); +.fi .SH DESCRIPTION Pass a char * as parameter, which should point to the null-terminated password to use for the TLS authentication method specified with the diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 index 917bc4ff5..0121ffaf5 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_TLSAUTH_TYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_PROXY_TLSAUTH_TYPE \- set proxy TLS authentication methods +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); +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 diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 index 7e54fbf0f..6bb2f1b62 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_TLSAUTH_USERNAME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_PROXY_TLSAUTH_USERNAME \- user name 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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_TLSAUTH_USERNAME, + char *user); +.fi .SH DESCRIPTION Pass a char * as parameter, which should point to the null-terminated username to use for the HTTPS proxy TLS authentication method specified with the diff --git a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 index fc33373bd..16be6aa5c 100644 --- a/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 +++ b/docs/libcurl/opts/CURLOPT_PROXY_TRANSFER_MODE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PROXY_TRANSFER_MODE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PROXY_TRANSFER_MODE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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 diff --git a/docs/libcurl/opts/CURLOPT_PUT.3 b/docs/libcurl/opts/CURLOPT_PUT.3 index 0581b7f50..5d30bce7d 100644 --- a/docs/libcurl/opts/CURLOPT_PUT.3 +++ b/docs/libcurl/opts/CURLOPT_PUT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_PUT 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_PUT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 @@ -39,6 +41,29 @@ This option is \fBdeprecated\fP since version 7.12.1. Use 0, disabled .SH PROTOCOLS HTTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + /* we want to use our own read function */ + curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback); + + /* 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, hd_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 Deprecated since 7.12.1. Do not use. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_QUOTE.3 b/docs/libcurl/opts/CURLOPT_QUOTE.3 index d5501f5d2..dd67ab7b0 100644 --- a/docs/libcurl/opts/CURLOPT_QUOTE.3 +++ b/docs/libcurl/opts/CURLOPT_QUOTE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,28 +20,38 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_QUOTE 3 "August 14, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_QUOTE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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 will be done before any other commands are issued (even before the CWD command for FTP). The linked list should be a fully valid list of 'struct curl_slist' 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. Disable this -operation again by setting a NULL to this option. 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 will stop at first failure. +the entire list afterwards with \fIcurl_slist_free_all(3)\fP. + +Disable this operation again by setting a NULL to this option. + +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 will +stop at first failure. The set of valid FTP commands depends on the server (see RFC959 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 will not know about it. + The valid SFTP commands are: .RS .IP "atime date file" diff --git a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 index 047748536..0abf28472 100644 --- a/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 +++ b/docs/libcurl/opts/CURLOPT_RANDOM_FILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RANDOM_FILE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RANDOM_FILE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RANDOM_FILE \- specify a source for random data +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 Pass a char * to a null-terminated file name. The file might be used to read from to seed the random engine for SSL and more. diff --git a/docs/libcurl/opts/CURLOPT_RANGE.3 b/docs/libcurl/opts/CURLOPT_RANGE.3 index cf77786f0..fcf712505 100644 --- a/docs/libcurl/opts/CURLOPT_RANGE.3 +++ b/docs/libcurl/opts/CURLOPT_RANGE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RANGE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RANGE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RANGE \- set byte range to request +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 * 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 @@ -50,7 +52,7 @@ Amazon's web services) support is limited. We suggest set resume position using \fICURLOPT_RESUME_FROM(3)\fP, set end (resume+size) position using \fICURLOPT_INFILESIZE(3)\fP and seek to the resume position before initiating the transfer for each part. For more information refer to -https://curl.haxx.se/mail/lib-2019-05/0012.html +https://curl.se/mail/lib-2019-05/0012.html Pass a NULL to this option to disable the use of ranges. diff --git a/docs/libcurl/opts/CURLOPT_READDATA.3 b/docs/libcurl/opts/CURLOPT_READDATA.3 index 778a6d044..590807532 100644 --- a/docs/libcurl/opts/CURLOPT_READDATA.3 +++ b/docs/libcurl/opts/CURLOPT_READDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,23 +20,25 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_READDATA 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_READDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_READDATA \- custom pointer passed to the read callback +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'll get as +\fICURLOPT_READFUNCTION(3)\fP option, this is the pointer you will get as input in the 4th argument to the callback. -If you don't specify a read callback but instead rely on the default internal +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 'void *'). -If you're using libcurl as a win32 DLL, you \fBMUST\fP use a +If you are using libcurl as a win32 DLL, you \fBMUST\fP use a \fICURLOPT_READFUNCTION(3)\fP if you set this option or you will experience crashes. .SH DEFAULT diff --git a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 index c6c3af113..c8cd61205 100644 --- a/docs/libcurl/opts/CURLOPT_READFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_READFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,18 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_READFUNCTION 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_READFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. @@ -47,9 +48,9 @@ area pointed at by the pointer \fIbuffer\fP. Returning 0 will signal 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've said you will upload N bytes and you +server expected it, like when you have said you will 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 won't come. +for the rest of the data that will 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 @@ -62,7 +63,7 @@ connection to pause. See \fIcurl_easy_pause(3)\fP for further details. that the callback wants, or it will be considered the final packet by the server end and the transfer will end there. -If you set this callback pointer to NULL, or don't set it at all, the default +If you set this callback pointer to NULL, or do not set it at all, the default internal read function will be used. It is doing an fread() on the FILE * userdata set with \fICURLOPT_READDATA(3)\fP. @@ -76,7 +77,7 @@ The default internal read callback is fread(). This is used for all protocols when doing uploads. .SH EXAMPLE .nf -size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userdata) +size_t read_callback(char *ptr, size_t size, size_t nmemb, void *userdata) { FILE *readhere = (FILE *)userdata; curl_off_t nread; diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 index 1bc786fe6..9691d463b 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_REDIR_PROTOCOLS 3 "February 18, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_REDIR_PROTOCOLS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_REDIR_PROTOCOLS \- set protocols allowed to redirect to +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 Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask limits what protocols libcurl may use in a transfer that it follows to in a @@ -76,7 +78,7 @@ CURLPROTO_TELNET CURLPROTO_TFTP .fi .SH DEFAULT -HTTP, HTTPS, FTP and FTPS (Since 7.65.2). +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. diff --git a/docs/libcurl/opts/CURLOPT_REFERER.3 b/docs/libcurl/opts/CURLOPT_REFERER.3 index b95f8974d..7311bf71c 100644 --- a/docs/libcurl/opts/CURLOPT_REFERER.3 +++ b/docs/libcurl/opts/CURLOPT_REFERER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_REFERER 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_REFERER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_REFERER \- set the HTTP referer header +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 will be used to set the Referer: header in the http request sent to the remote server. This @@ -59,3 +61,4 @@ Returns CURLE_OK if HTTP support is enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. .SH "SEE ALSO" .BR CURLOPT_USERAGENT "(3), " CURLOPT_HTTPHEADER "(3), " +.BR CURLINFO_REFERER "(3), " diff --git a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 index 04ed9f3ad..b48898aa6 100644 --- a/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 +++ b/docs/libcurl/opts/CURLOPT_REQUEST_TARGET.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_REQUEST_TARGET 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_REQUEST_TARGET 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_REQUEST_TARGET \- specify an alternative target for this request +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 * to string which libcurl uses in the upcoming request instead of the path as extracted from the URL. diff --git a/docs/libcurl/opts/CURLOPT_RESOLVE.3 b/docs/libcurl/opts/CURLOPT_RESOLVE.3 index 43763cfb8..2c2142334 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVE.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RESOLVE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RESOLVE 3 "December 07, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_RESOLVE \- provide custom host name to IP address resolves @@ -37,36 +37,41 @@ 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 name resolve string should be written using the format -HOST:PORT:ADDRESS[,ADDRESS]... where HOST is the name libcurl will try -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. +Each resolve rule to add should be written using the format + +.nf + [+]HOST:PORT:ADDRESS[,ADDRESS] +.fi + +\&... where HOST is the name libcurl will try 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. This option effectively pre-populates the DNS cache with entries for the host+port pair so redirects and everything that operations against the -HOST+PORT will instead use your provided ADDRESS. Addresses set with -\fICURLOPT_RESOLVE(3)\fP will not time-out from the DNS cache like ordinary -entries. +HOST+PORT will instead use your provided ADDRESS. -If the DNS cache already have an entry for the given host+port pair, then -this entry will be removed and a new entry will be created. This is because -old entry may have have different addresses or be ordinary entries with -time-outs. +The optional leading "+" specifies that the new entry should time-out. Entries +added without the leading plus character will never time-out whereas entries +added with "+HOST:..." will time-out just like ordinary DNS cache entries. -The provided ADDRESS set by this option will be used even if -\fICURLOPT_IPRESOLVE(3)\fP is set to make libcurl use another IP version. +If the DNS cache already has an entry for the given host+port pair, the new +entry will override the former one. -Remove names from the DNS cache again, to stop providing these fake resolves, -by including a string in the linked list that uses the format -\&"-HOST:PORT". The host name must be prefixed with a dash, and the host name -and port number must exactly match what was already added previously. +An ADDRESS provided by this option will only be used if not restricted by the +setting of \fICURLOPT_IPRESOLVE(3)\fP to a different IP version. -Support for providing the ADDRESS within [brackets] was added in 7.57.0. +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 -Support for providing multiple IP addresses per entry was added in 7.59.0. +.nf + -HOST:PORT +.fi + +The entry to remove must be prefixed with a dash, and the host name and port +number must exactly match what was added previously. .SH DEFAULT NULL .SH PROTOCOLS @@ -92,7 +97,15 @@ curl_slist_free_all(host); .fi .SH AVAILABILITY 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. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" -.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " CURLOPT_CONNECT_TO "(3), " +.BR CURLOPT_IPRESOLVE "(3), " CURLOPT_DNS_CACHE_TIMEOUT "(3), " +.BR CURLOPT_CONNECT_TO "(3), " diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 index 4347e49ee..165bd4091 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_DATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RESOLVER_START_DATA 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RESOLVER_START_DATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RESOLVER_START_DATA \- custom pointer passed to the resolver start callback +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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_RESOLVER_START_DATA, + void *pointer); +.fi .SH DESCRIPTION Pass a \fIpointer\fP that will be untouched by libcurl and passed as the third argument in the resolver start callback set with diff --git a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 index 9b8250c61..736cd8360 100644 --- a/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_RESOLVER_START_FUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RESOLVER_START_FUNCTION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RESOLVER_START_FUNCTION 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RESOLVER_START_FUNCTION \- set callback to be called before a new resolve request is started +CURLOPT_RESOLVER_START_FUNCTION \- callback called before a new name resolve is started .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 index fa0484c7c..4fb775d0c 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RESUME_FROM 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RESUME_FROM 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RESUME_FROM \- set a point to resume transfer from +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 diff --git a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 index 982655239..0051736b3 100644 --- a/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_RESUME_FROM_LARGE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RESUME_FROM_LARGE 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RESUME_FROM_LARGE 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RESUME_FROM_LARGE \- set a point to resume transfer from +CURLOPT_RESUME_FROM_LARGE \- offset to resume transfer from .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 index c944cf635..e6df571ca 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_CLIENT_CSEQ.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_CLIENT_CSEQ 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_CLIENT_CSEQ 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_CLIENT_CSEQ \- set the RTSP client CSEQ number +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 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 index 49a5c7b4f..aea599487 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_REQUEST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_REQUEST 3 "July 16, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_REQUEST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_REQUEST \- specify RTSP request +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, diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 index 96fb872cd..e87a781d9 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_SERVER_CSEQ.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_SERVER_CSEQ 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_SERVER_CSEQ 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_SERVER_CSEQ \- set the RTSP server CSEQ number +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->Client request. \fBNOTE\fP: this feature (listening for Server requests) is diff --git a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 index 131a21053..88b9e7061 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_SESSION_ID 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_SESSION_ID 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_SESSION_ID \- set RTSP session ID +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 * 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 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 index 6d8c45081..38c14d2e4 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_STREAM_URI 3 "July 16, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_STREAM_URI 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_STREAM_URI \- set RTSP stream URI +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 diff --git a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 index 96c262fb1..0e092d1e1 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 +++ b/docs/libcurl/opts/CURLOPT_RTSP_TRANSPORT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_RTSP_TRANSPORT 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_RTSP_TRANSPORT 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_RTSP_TRANSPORT \- set RTSP Transport: header +CURLOPT_RTSP_TRANSPORT \- RTSP Transport: header .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 index 35e6c001c..e80f62b06 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 +++ b/docs/libcurl/opts/CURLOPT_SASL_AUTHZID.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SASL_AUTHZID 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SASL_AUTHZID 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SASL_AUTHZID \- authorisation 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 * as parameter, which should be pointing to the null-terminated authorisation identity (authzid) for the transfer. Only applicable to the PLAIN diff --git a/docs/libcurl/opts/CURLOPT_SASL_IR.3 b/docs/libcurl/opts/CURLOPT_SASL_IR.3 index 09a2becab..5cc405d32 100644 --- a/docs/libcurl/opts/CURLOPT_SASL_IR.3 +++ b/docs/libcurl/opts/CURLOPT_SASL_IR.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SASL_IR 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SASL_IR 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SASL_IR \- enable sending initial response in first packet +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 will send the initial response to the server in the first authentication packet in order to reduce the number of diff --git a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 index 4c71c5a6c..f85051cf2 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SEEKDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SEEKDATA 3 "October 31, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SEEKDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SEEKDATA \- custom pointer passed to the seek callback +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'll get as +\fICURLOPT_SEEKFUNCTION(3)\fP option, this is the pointer you will get as input. .SH DEFAULT -If you don't set this, NULL is passed to the callback. +If you do not set this, NULL is passed to the callback. .SH PROTOCOLS HTTP, FTP, SFTP .SH EXAMPLE diff --git a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 index d740abfc0..cee5c8b6d 100644 --- a/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SEEKFUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SEEKFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SEEKFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream @@ -31,7 +31,7 @@ CURLOPT_SEEKFUNCTION \- user callback for seeking in input stream /* 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 can't be done, so +#define CURL_SEEKFUNC_CANTSEEK 2 /* tell libcurl seeking cannot be done, so libcurl might try other means instead */ int seek_callback(void *userp, curl_off_t offset, int origin); diff --git a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 index 941177228..84d0b48bb 100644 --- a/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 +++ b/docs/libcurl/opts/CURLOPT_SERVICE_NAME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SERVICE_NAME 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SERVICE_NAME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * as parameter to a string holding the \fIname\fP of the service for DIGEST-MD5, SPNEGO and Kerberos 5 authentication mechanisms. The default diff --git a/docs/libcurl/opts/CURLOPT_SHARE.3 b/docs/libcurl/opts/CURLOPT_SHARE.3 index 193d811a4..ebf3ca795 100644 --- a/docs/libcurl/opts/CURLOPT_SHARE.3 +++ b/docs/libcurl/opts/CURLOPT_SHARE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SHARE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SHARE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SHARE \- specify share handle to use +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, @@ -39,7 +41,7 @@ data. If the curl handles are used simultaneously in multiple threads, you If you add a share that is set to share cookies, your easy handle will use that cookie cache and get the cookie engine enabled. If you unshare an object -that was using cookies (or change to another object that doesn't share +that was using cookies (or change to another object that does not share cookies), the easy handle will get its cookie engine disabled. Data that the share object is not set to share will be dealt with the usual diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 index cc43ac453..d1d52b0c8 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SOCKOPTDATA 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SOCKOPTDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SOCKOPTDATA \- custom pointer to pass to sockopt callback +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 will be untouched by libcurl and passed as the first argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 index efce2a6f6..c8a99543e 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SOCKOPTFUNCTION 3 "May 15, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SOCKOPTFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SOCKOPTFUNCTION \- set callback for setting socket options +CURLOPT_SOCKOPTFUNCTION \- callback for setting socket options .SH SYNOPSIS .nf #include <curl/curl.h> @@ -55,7 +55,7 @@ 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 weren't passed to this callback). +(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 diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 index 1dc698fd1..4bc4411a2 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_AUTH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SOCKS5_AUTH 3 "April 27, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SOCKS5_AUTH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SOCKS5_AUTH \- set allowed methods for SOCKS5 proxy authentication +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 diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 index 7bbae66e6..89dbb34f6 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_NEC.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SOCKS5_GSSAPI_NEC 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SOCKS5_GSSAPI_NEC \- set socks proxy gssapi negotiation protection +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 RFC1961 says in section diff --git a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 index 59d5b63cb..bce2f48cf 100644 --- a/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 +++ b/docs/libcurl/opts/CURLOPT_SOCKS5_GSSAPI_SERVICE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SOCKS5_GSSAPI_SERVICE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 index 09b8b403d..e0a30c0d5 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_AUTH_TYPES.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_AUTH_TYPES 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_AUTH_TYPES 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_AUTH_TYPES \- set desired auth types for SFTP and SCP +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, diff --git a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 index 9fea8611c..87334321b 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_COMPRESSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_COMPRESSION 3 "August 10, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_COMPRESSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_COMPRESSION \- enables compression / decompression of SSH traffic +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. diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 index cb8b3fa6d..d1dcf2b29 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 3 "November 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- checksum of SSH server public key +CURLOPT_SSH_HOST_PUBLIC_KEY_MD5 \- MD5 checksum of SSH server public key .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 new file mode 100644 index 000000000..83d8ab016 --- /dev/null +++ b/docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 @@ -0,0 +1,61 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.\" +.TH CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + +.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); +.SH DESCRIPTION +Pass a char * pointing to a string containing a Base64-encoded SHA256 +hash of the remote host's public key. +The transfer will fail if the given hash does not match the hash the +remote host provides. + +.SH DEFAULT +NULL +.SH PROTOCOLS +SCP and SFTP +.SH EXAMPLE +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/file"); + curl_easy_setopt(curl, CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256, + "NDVkMTQxMGQ1ODdmMjQ3MjczYjAyOTY5MmRkMjVmNDQ="); + ret = curl_easy_perform(curl); + curl_easy_cleanup(curl); +} +.fi +.SH AVAILABILITY +Added in 7.80.0 +Requires the libssh2 back-end. +.SH RETURN VALUE +Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or +CURLE_OUT_OF_MEMORY if there was insufficient heap space. +.SH "SEE ALSO" +.BR CURLOPT_SSH_PUBLIC_KEYFILE "(3), " CURLOPT_SSH_AUTH_TYPES "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 index 2c09702f0..7bcd6cac6 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_KEYDATA 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_KEYDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_KEYDATA \- pointer to pass to the SSH key callback +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 will be passed along verbatim to the callback set with \fICURLOPT_SSH_KEYFUNCTION(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 index fcd95a24f..5460d915b 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_KEYFUNCTION 3 "July 15, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_KEYFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic @@ -32,7 +32,7 @@ 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 can't answer right + CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right now so this causes a CURLE_DEFER error but otherwise the connection will be left intact etc */ @@ -77,19 +77,19 @@ codes to tell libcurl how to act: .IP CURLKHSTAT_FINE_REPLACE The new host+key is accepted and libcurl will replace the old host+key into the known_hosts file before continuing with the connection. This will also -add the new host+key combo to the known_host pool kept in memory if it wasn't +add 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 will append it to the known_hosts file before continuing with the connection. This will also add the host+key combo -to the known_host pool kept in memory if it wasn't already present there. The +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 will continue with the connection. This will -also add the host+key combo to the known_host pool kept in memory if it wasn't +also add 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 will deny the connection to continue and it diff --git a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 index dcdc90915..8f7a89b6a 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_KNOWNHOSTS 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_KNOWNHOSTS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSH_KNOWNHOSTS \- file name 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 file name of the known_host file to use. The known_hosts file should use the OpenSSH file diff --git a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 index 402e57b33..b9cd0b8d4 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_PRIVATE_KEYFILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_PRIVATE_KEYFILE 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_PRIVATE_KEYFILE \- set private key file for SSH auth +CURLOPT_SSH_PRIVATE_KEYFILE \- private key file for SSH auth .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 index 75c05ecd9..d7c8d9d90 100644 --- a/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 +++ b/docs/libcurl/opts/CURLOPT_SSH_PUBLIC_KEYFILE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSH_PUBLIC_KEYFILE 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSH_PUBLIC_KEYFILE \- set public key file for SSH auth +CURLOPT_SSH_PUBLIC_KEYFILE \- public key file for SSH auth .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT.3 b/docs/libcurl/opts/CURLOPT_SSLCERT.3 index 5af0e9569..c78de5645 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT.3 +++ b/docs/libcurl/opts/CURLOPT_SSLCERT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLCERT 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLCERT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLCERT \- set SSL client certificate +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 file name of your client certificate. The default format is "P12" on diff --git a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 index 324996a3b..9d6db209a 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_SSLCERTTYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2015, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLCERTTYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLCERTTYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLCERTTYPE \- specify type of the client SSL certificate +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 diff --git a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 index ed13d6cfc..bf188d9f8 100644 --- a/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_SSLCERT_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,13 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLCERT_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_SSLCERT_BLOB 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .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); +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 @@ -60,8 +64,8 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL, Secure -Transport and Schannel backends. +Added in 7.71.0. This option is supported by the OpenSSL, Secure Transport and +Schannel backends. .SH RETURN VALUE Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 index 7be56ead8..b55ec0822 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE.3 +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLENGINE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLENGINE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLENGINE \- set SSL engine identifier +CURLOPT_SSLENGINE \- SSL engine identifier .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 will be used as the identifier for the crypto engine you want to use for your private key. diff --git a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 index 559a4f056..35e5a8227 100644 --- a/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 +++ b/docs/libcurl/opts/CURLOPT_SSLENGINE_DEFAULT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLENGINE_DEFAULT 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLENGINE_DEFAULT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY.3 b/docs/libcurl/opts/CURLOPT_SSLKEY.3 index ce1208a25..81e4aca8c 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLKEY 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLKEY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLKEY \- specify private keyfile for TLS and SSL client cert +CURLOPT_SSLKEY \- private keyfile 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 file name of your private key. The default format is "PEM" and can be diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 index 2b71c0817..43a68edbe 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLKEYTYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLKEYTYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLKEYTYPE \- set type of the private key file +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" and "ENG". diff --git a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 index 1f657c8ec..ed0dbfb58 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 +++ b/docs/libcurl/opts/CURLOPT_SSLKEY_BLOB.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,8 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLKEY_BLOB 3 "24 Jun 2020" "libcurl 7.71.0" "curl_easy_setopt options" +.TH CURLOPT_SSLKEY_BLOB 3 "October 25, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .SH NAME CURLOPT_SSLKEY_BLOB \- private key for client cert from memory blob .SH SYNOPSIS @@ -67,7 +68,7 @@ if(curl) { } .fi .SH AVAILABILITY -Added in libcurl 7.71.0. This option is supported by the OpenSSL backends. +Added in 7.71.0. This option is supported by the OpenSSL backends. .SH RETURN VALUE Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or CURLE_OUT_OF_MEMORY if there was insufficient heap space. diff --git a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 index 7b12b9d7a..90d19b7b8 100644 --- a/docs/libcurl/opts/CURLOPT_SSLVERSION.3 +++ b/docs/libcurl/opts/CURLOPT_SSLVERSION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSLVERSION 3 "October 31, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSLVERSION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSLVERSION \- set preferred TLS/SSL version +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. @@ -44,9 +46,9 @@ 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 (but not SSLv3) +SSL v2 - refused .IP CURL_SSLVERSION_SSLv3 -SSL v3 (but not SSLv2) +SSL v3 - refused .IP CURL_SSLVERSION_TLSv1_0 TLS v1.0 or later (Added in 7.34.0) .IP CURL_SSLVERSION_TLSv1_1 @@ -103,6 +105,8 @@ if(curl) { } .fi .SH AVAILABILITY +SSLv2 and SSLv3 are refused completely since curl 7.77.0 + 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. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 index 2c6ef0d00..d6066507d 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_CIPHER_LIST 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_CIPHER_LIST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_CIPHER_LIST \- specify ciphers to use for TLS +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 *, pointing to a null-terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, @@ -35,21 +37,21 @@ it consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, \&!, \&- and \&+ can be used as operators. -For OpenSSL and GnuTLS valid examples of cipher lists include 'RC4-SHA', -\'SHA1+DES\', 'TLSv1' and 'DEFAULT'. The default list is normally set when you -compile OpenSSL. - -You'll find more details about cipher lists on this URL: +For OpenSSL and GnuTLS valid examples of cipher lists include \fBRC4-SHA\fP, +\fBSHA1+DES\fP, \fBTLSv1\fP and \fBDEFAULT\fP. The default list is normally +set when you compile OpenSSL. - https://curl.haxx.se/docs/ssl-ciphers.html - -For NSS, valid examples of cipher lists include 'rsa_rc4_128_md5', -\'rsa_aes_128_sha\', etc. With NSS you don't add/remove ciphers. If one uses +For NSS, valid examples of cipher lists include \fBrsa_rc4_128_md5\fP, +\fBrsa_aes_128_sha\fP, etc. With NSS you do not add/remove ciphers. If one uses this option then all known ciphers are disabled and only those passed in are enabled. -For WolfSSL, valid examples of cipher lists include -\'ECDHE-RSA-RC4-SHA\', 'AES256-SHA:AES256-SHA256', etc. +For WolfSSL, valid examples of cipher lists include \fBECDHE-RSA-RC4-SHA\fP, +\fBAES256-SHA:AES256-SHA256\fP, etc. + +you will 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. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 index 167fe327a..2d984d238 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_DATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_CTX_DATA 3 "June 02, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_CTX_DATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_CTX_DATA \- custom pointer passed to ssl_ctx callback +CURLOPT_SSL_CTX_DATA \- pointer passed to ssl_ctx 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'll get as third +\fICURLOPT_SSL_CTX_FUNCTION(3)\fP, this is the pointer you will get as third parameter. .SH DEFAULT NULL @@ -47,11 +49,11 @@ All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) { X509_STORE *store; - X509 *cert=NULL; + X509 *cert = NULL; BIO *bio; - char *mypem = (char *)parm; + char *mypem = parm; /* get a BIO */ - bio=BIO_new_mem_buf(mypem, -1); + 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 */ @@ -60,10 +62,10 @@ static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm) 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); + store = SSL_CTX_get_cert_store((SSL_CTX *)sslctx); /* add our certificate to this store */ - if(X509_STORE_add_cert(store, cert)==0) + if(X509_STORE_add_cert(store, cert) == 0) printf("error adding certificate\\n"); /* decrease reference counts */ @@ -89,20 +91,21 @@ int main(void) "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\\n" "-----END CERTIFICATE-----\\n"; - rv=curl_global_init(CURL_GLOBAL_ALL); - ch=curl_easy_init(); - rv=curl_easy_setopt(ch, CURLOPT_SSLCERTTYPE, "PEM"); - rv=curl_easy_setopt(ch, CURLOPT_SSL_VERIFYPEER, 1L); - rv=curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/"); + 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/"); /* Retrieve page using cacerts' certificate -> will succeed * load the certificate by installing a function doing the necessary * "modifications" to the SSL CONTEXT just before link init */ - rv=curl_easy_setopt(ch, CURLOPT_SSL_CTX_FUNCTION, *sslctx_function); - rv=curl_easy_setopt(ch, CURLOPT_SSL_CTX_DATA, mypem); - rv=curl_easy_perform(ch); - if(rv==CURLE_OK) + 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"); diff --git a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 index ed238895c..9f377d0b8 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_CTX_FUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_CTX_FUNCTION 3 "June 02, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_CTX_FUNCTION 3 "July 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL, wolfSSL or mbedTLS @@ -63,14 +63,95 @@ 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. + +WARNING: If you are using DNS-over-HTTPS (DoH) via \fICURLOPT_DOH_URL(3)\fP +then the CTX callback will also be called for those transfers and the curl +handle is set to an internal handle. \fBThis behavior is subject to change.\fP +We recommend before performing your transfer set \fICURLOPT_PRIVATE(3)\fP on +your curl handle so you can identify it in the CTX 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. .SH DEFAULT NULL .SH PROTOCOLS All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. .SH EXAMPLE -See cacertinmem.c in docs/examples directory for usage 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 == NULL) + 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/"); + + /* Retrieve page using cacerts' certificate -> will succeed + * load the certificate by installing a function doing the necessary + * "modifications" to the SSL CONTEXT just before link init + */ + 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"); -https://curl.haxx.se/libcurl/c/cacertinmem.html + curl_easy_cleanup(ch); + curl_global_cleanup(); + return rv; +} +.fi .SH AVAILABILITY Added in 7.11.0 for OpenSSL, in 7.42.0 for wolfSSL and in 7.54.0 for mbedTLS. Other SSL backends are not supported. diff --git a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 index db2d87375..ee2d74671 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_EC_CURVES 3 "August 29, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_EC_CURVES 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_EC_CURVES \- set key exchange curves +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 *alg_list); +.fi .SH DESCRIPTION Pass a string as parameter with a colon delimited list of (EC) algorithms. This option defines the client's key exchange algorithms in the SSL handshake (if diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 index db7b7c2b1..80cfb926d 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_ALPN.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_ENABLE_ALPN 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_ENABLE_ALPN 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_ENABLE_ALPN \- enable ALPN +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 diff --git a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 index 5f4fae639..cba7cb5b7 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_ENABLE_NPN.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_ENABLE_NPN 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_ENABLE_NPN 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_ENABLE_NPN \- enable NPN +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 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 diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 index c0bb76717..a68ba5c13 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_FALSESTART 3 "May 15, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_FALSESTART 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_FALSESTART \- enable TLS false start +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. @@ -54,3 +56,5 @@ Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends. .SH RETURN VALUE Returns CURLE_OK if false start is supported by the SSL backend, otherwise returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_TCP_FASTOPEN "(3), " diff --git a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 index 46b5f08f9..ec46537d7 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_OPTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,20 +20,22 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_OPTIONS 3 "July 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_OPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_OPTIONS \- set SSL behavior options +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 isn't used or this bit is set to 0, +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 @@ -43,7 +45,7 @@ supported for Secure Transport, NSS and OpenSSL. 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' -Untrusted Publishers block list which it seems can't be bypassed. (Added in +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 @@ -61,6 +63,14 @@ Tell libcurl to use the operating system's native CA store for certificate verification. Works only on Windows when built to use OpenSSL. This option is experimental and behavior is subject to change. (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 diff --git a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 index fdc1077c1..b9879ebfb 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_SESSIONID_CACHE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_SESSIONID_CACHE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_SESSIONID_CACHE 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_SESSIONID_CACHE \- enable/disable use of the SSL session-ID cache +CURLOPT_SSL_SESSIONID_CACHE \- use the SSL session-ID cache .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 index 219054136..6a9419b16 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_VERIFYHOST 3 "July 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_VERIFYHOST 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSL_VERIFYHOST \- verify the certificate's 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 as parameter specifying what to \fIverify\fP. diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 index 47d5a26b9..f3314efbb 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYPEER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,19 +20,21 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_VERIFYPEER 3 "June 24, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_VERIFYPEER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSL_VERIFYPEER \- verify the peer's 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's -certificate. A value of 1 means curl verifies; 0 (zero) means it doesn't. +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, @@ -50,7 +52,7 @@ 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_SSL_VERIFYHOST(3)\fP for that. The check that the -host name in the certificate is valid for the host name you're connecting to +host name in the certificate is valid for the host name 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 diff --git a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 index fcbfe6fd7..5a5784776 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 +++ b/docs/libcurl/opts/CURLOPT_SSL_VERIFYSTATUS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SSL_VERIFYSTATUS 3 "October 09, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SSL_VERIFYSTATUS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_SSL_VERIFYSTATUS \- verify the certificate's 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. diff --git a/docs/libcurl/opts/CURLOPT_STDERR.3 b/docs/libcurl/opts/CURLOPT_STDERR.3 index ce20f2da8..c437bb52b 100644 --- a/docs/libcurl/opts/CURLOPT_STDERR.3 +++ b/docs/libcurl/opts/CURLOPT_STDERR.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,18 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_STDERR 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_STDERR 3 "December 06, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 win32 DLL, this option will cause an exception +and 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 @@ -53,3 +59,4 @@ Always Returns CURLE_OK .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_NOPROGRESS "(3), " +.BR CURLOPT_DEBUGFUNCTION "(3) " diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 index 38da9c83d..ec25ee5c8 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_STREAM_DEPENDS 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_STREAM_DEPENDS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_STREAM_DEPENDS \- set stream this transfer depends on +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); +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 diff --git a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 index f472a75f3..fef001f5e 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_DEPENDS_E.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_STREAM_DEPENDS_E 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_STREAM_DEPENDS_E 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_STREAM_DEPENDS_E \- set stream this transfer depends on exclusively +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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_STREAM_DEPENDS_E, + 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 exclusively. That means it diff --git a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 index c063050f9..3dd4d1dd7 100644 --- a/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 +++ b/docs/libcurl/opts/CURLOPT_STREAM_WEIGHT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_STREAM_WEIGHT 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_STREAM_WEIGHT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_STREAM_WEIGHT \- set numerical stream weight +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. diff --git a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 index e23b5574e..7124edcea 100644 --- a/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 +++ b/docs/libcurl/opts/CURLOPT_SUPPRESS_CONNECT_HEADERS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "April 28, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_SUPPRESS_CONNECT_HEADERS 3 "September 08, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SUPPRESS_CONNECT_HEADERS \- Suppress proxy CONNECT response headers from user callbacks +CURLOPT_SUPPRESS_CONNECT_HEADERS \- suppress proxy CONNECT response headers from user callbacks .SH SYNOPSIS .nf #include <curl/curl.h> diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 index 1a39db2df..e7d646903 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TCP_FASTOPEN 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TCP_FASTOPEN 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TCP_FASTOPEN \- enable TCP Fast Open +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. @@ -53,3 +55,5 @@ El Capitan. .SH RETURN VALUE Returns CURLE_OK if fast open is supported by the operating system, otherwise returns CURLE_NOT_BUILT_IN. +.SH SEE ALSO +.BR CURLOPT_SSL_FALSESTART "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 index 3a4a69ed0..f6b332f99 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPALIVE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TCP_KEEPALIVE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TCP_KEEPALIVE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TCP_KEEPALIVE \- enable TCP keep-alive probing +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 will be sent. The delay and frequency of these probes can be controlled by the diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 index 26bb554ee..589b2ab5a 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPIDLE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TCP_KEEPIDLE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TCP_KEEPIDLE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TCP_KEEPIDLE \- set TCP keep-alive idle time wait +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, that the operating system will wait while the connection is idle before sending keepalive probes. Not all diff --git a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 index b4d2c6f14..2aeecb9d6 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_KEEPINTVL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TCP_KEEPINTVL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TCP_KEEPINTVL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TCP_KEEPINTVL \- set TCP keep-alive interval +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, that the operating system will wait between sending keepalive probes. Not all operating systems support this diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 index 53a41d72f..e71ee4615 100644 --- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 +++ b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TCP_NODELAY 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TCP_NODELAY 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TCP_NODELAY \- set the TCP_NODELAY option +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 TCP_NODELAY option is to be set or cleared (1L = set, 0 = clear). The option is set by default. This will have no effect @@ -52,7 +54,7 @@ All CURL *curl = curl_easy_init(); if(curl) { curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); - /* disable Nagle */ + /* leave Nagle enabled */ curl_easy_setopt(curl, CURLOPT_TCP_NODELAY, 0); curl_easy_perform(curl); } diff --git a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 index 913a5f3d6..5d1d42edf 100644 --- a/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_TELNETOPTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TELNETOPTIONS 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TELNETOPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TELNETOPTIONS \- custom telnet options +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 diff --git a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 index 55bd09dde..eea9902fd 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_BLKSIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TFTP_BLKSIZE 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TFTP_BLKSIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 RFC2348 is 8-65464 bytes. The default of 512 bytes will be used if this option diff --git a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 index 9d9ab50ba..a9156f0e0 100644 --- a/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 +++ b/docs/libcurl/opts/CURLOPT_TFTP_NO_OPTIONS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TFTP_NO_OPTIONS 3 "April 06, 2016" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TFTP_NO_OPTIONS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TFTP_NO_OPTIONS \- Do not send TFTP options requests. +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 RFC2347, RFC2348 and RFC2349 from read and write requests (RRQs/WRQs). @@ -70,3 +72,5 @@ if(curl) { Added in 7.48.0 .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. +.SH SEE ALSO +.BR CURLOPT_TFTP_BLKSIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 index 00e9432a9..0afc10b27 100644 --- a/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 +++ b/docs/libcurl/opts/CURLOPT_TIMECONDITION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TIMECONDITION 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TIMECONDITION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 index 19d574979..6a7df44be 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TIMEOUT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TIMEOUT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TIMEOUT \- set maximum time the request is allowed to take +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 libcurl transfer operation to take. Normally, name diff --git a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 index 103692b12..421efbfdd 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEOUT_MS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TIMEOUT_MS 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TIMEOUT_MS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TIMEOUT_MS \- set maximum time the request is allowed to take +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. Normally, diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 index b352f671c..6deebe967 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TIMEVALUE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TIMEVALUE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TIMEVALUE \- set time value for conditional +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 will be used in a condition as specified with diff --git a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 index 4ebfb017b..cc2a2a83e 100644 --- a/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_TIMEVALUE_LARGE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TIMEVALUE_LARGE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TIMEVALUE_LARGE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TIMEVALUE_LARGE \- set time value for conditional +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); +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 will be used in a condition as diff --git a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 index abd767b48..bcfe8aa24 100644 --- a/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 +++ b/docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,22 +20,24 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TLS13_CIPHERS 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TLS13_CIPHERS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TLS13_CIPHERS \- specify ciphers suites to use for TLS 1.3 +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 *, 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. -You'll find more details about cipher lists on this URL: +you will find more details about cipher lists on this URL: - https://curl.haxx.se/docs/ssl-ciphers.html + https://curl.se/docs/ssl-ciphers.html This option is currently used only when curl is built to use OpenSSL 1.1.1 or later. If you are using a different SSL backend you can try setting TLS 1.3 diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 index 7b9a97cc1..83186d119 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TLSAUTH_PASSWORD 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TLSAUTH_PASSWORD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 * as parameter, which should point to the null-terminated password to use for the TLS authentication method specified with the @@ -37,7 +39,7 @@ to use for the TLS authentication method specified with the The application does not have to keep the string around after setting this option. -This feature relies in TLS SRP which doesn't work with TLS 1.3. +This feature relies in TLS SRP which does not work with TLS 1.3. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 index e52efb45b..7e4811460 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TLSAUTH_TYPE 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TLSAUTH_TYPE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TLSAUTH_TYPE \- set TLS authentication methods +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". @@ -42,7 +44,7 @@ options. The application does not have to keep the string around after setting this option. -TLS SRP doesn't work with TLS 1.3. +TLS SRP does not work with TLS 1.3. .SH DEFAULT blank .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 index ceecec0e0..a334ce684 100644 --- a/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 +++ b/docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TLSAUTH_USERNAME 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TLSAUTH_USERNAME 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_TLSAUTH_USERNAME \- user name 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 * as parameter, which should point to the null-terminated username to use for the TLS authentication method specified with the @@ -37,7 +39,7 @@ to use for the TLS authentication method specified with the The application does not have to keep the string around after setting this option. -This feature relies in TLS SRP which doesn't work with TLS 1.3. +This feature relies in TLS SRP which does not work with TLS 1.3. .SH DEFAULT NULL .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 b/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 index d5133d7bb..21c75754e 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 +++ b/docs/libcurl/opts/CURLOPT_TRAILERDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,15 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TRAILERDATA 3 "October 31, 2019" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TRAILERDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TRAILERDATA \- Custom pointer passed to the trailing headers callback +CURLOPT_TRAILERDATA \- pointer passed to trailing headers callback .SH SYNOPSIS +.nf #include <curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERDATA, void *userdata); -.SH DESCRIPTION: +.fi +.SH DESCRIPTION Data pointer to be passed to the HTTP trailer callback function. .SH DEFAULT NULL @@ -46,5 +48,7 @@ curl_easy_setopt(hndl, CURLOPT_TRAILERDATA, &data); A more complete example can be found in examples/http_trailers.html .SH AVAILABILITY This option was added in curl 7.64.0 and is present if HTTP support is enabled +.SH RETURN VALUE +Returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_TRAILERFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 index 42bcc1636..2c61b3ed0 100644 --- a/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_TRAILERFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,16 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TRAILERFUNCTION 3 "October 03, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TRAILERFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_TRAILERFUNCTION \- Set callback for sending trailing headers +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); +CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRAILERFUNCTION, + curl_trailer_callback *func); +.fi .SH DESCRIPTION Pass a pointer to a callback function. @@ -67,7 +70,7 @@ HTTP static int trailer_cb(struct curl_slist **tr, void *data) { /* libcurl will free the list */ - tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); + *tr = curl_slist_append(*tr, "My-super-awesome-trailer: trailer-stuff"); return CURL_TRAILERFUNC_OK; } @@ -98,5 +101,7 @@ if(curl) { } .SH AVAILABILITY This option was added in curl 7.64.0 and is present if HTTP support is enabled +.SH RETURN VALUE +Returns CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_TRAILERDATA "(3), " diff --git a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 index cb59cb7e7..746c2824a 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 +++ b/docs/libcurl/opts/CURLOPT_TRANSFERTEXT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TRANSFERTEXT 3 "May 31, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TRANSFERTEXT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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 diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 index c3cc93f8d..bc641de43 100644 --- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 +++ b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_TRANSFER_ENCODING 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_TRANSFER_ENCODING 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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); +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. diff --git a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 index fa6544ff0..564f1e41d 100644 --- a/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 +++ b/docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_UNIX_SOCKET_PATH 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_UNIX_SOCKET_PATH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_UNIX_SOCKET_PATH \- set Unix domain socket +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. An @@ -41,42 +43,41 @@ curl does not need to 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 -.BR CURLOPT_TCP_NODELAY "(3) -are not supported. Proxy options such as -.BR CURLOPT_PROXY "(3) -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. +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. .SH DEFAULT Default is NULL, meaning that no Unix domain sockets are used. .SH PROTOCOLS -All protocols except for file:// and FTP are supported in theory. HTTP, IMAP, +All protocols except for FILE and FTP are supported in theory. HTTP, IMAP, POP3 and SMTP should in particular work (including their SSL/TLS variants). .SH EXAMPLE -Given that you have an nginx server running, listening on /tmp/nginx.sock, you +Given that you have an HTTP server running listening on /tmp/httpd.sock, you can request an HTTP resource with: .nf - curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/nginx.sock"); - curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/"); + curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, "/tmp/httpd.sock"); + curl_easy_setopt(curl_handle, CURLOPT_URL, "http://localhost/"); .fi -If you are on Linux and somehow have a need for paths larger than 107 bytes, you -could use the proc filesystem to bypass the limitation: +If you are on Linux and somehow have a need for paths larger than 107 bytes, +you could use the proc 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/nginx.sock", dirfd); - curl_easy_setopt(curl_handle, CURLOPT_UNIX_SOCKET_PATH, path); - /* Be sure to keep dirfd valid until you discard the handle */ + 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 -Since 7.40.0. +Added in 7.40.0. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" +.BR CURLOPT_ABSTRACT_UNIX_SOCKET "(3), " .BR CURLOPT_OPENSOCKETFUNCTION "(3), " unix "(7), " diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 index 92fede0ae..b54de3bb7 100644 --- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 +++ b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_UNRESTRICTED_AUTH 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_UNRESTRICTED_AUTH 3 "November 04, 2020" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too diff --git a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 index 91eea1ba6..d04a3e8d8 100644 --- a/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 +++ b/docs/libcurl/opts/CURLOPT_UPKEEP_INTERVAL_MS.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,13 +20,17 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_UPKEEP_INTERVAL_MS 3 "31 Oct 2018" "libcurl 7.62.0" "curl_easy_setopt options" +.TH CURLOPT_UPKEEP_INTERVAL_MS 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" + .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); +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 @@ -42,6 +46,8 @@ 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 +All .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -71,3 +77,6 @@ if(curl) { Added in 7.62.0 .SH RETURN VALUE Returns CURLE_OK +.SH SEE ALSO +.BR CURLOPT_TCP_KEEPALIVE "(3), " + diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD.3 b/docs/libcurl/opts/CURLOPT_UPLOAD.3 index 668ee89c9..48f348807 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD.3 +++ b/docs/libcurl/opts/CURLOPT_UPLOAD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_UPLOAD 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_UPLOAD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_UPLOAD \- enable data upload +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 @@ -66,7 +68,7 @@ if(curl) { /* 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've been told! */ + /* Now run off and do what you have been told! */ curl_easy_perform(curl); } .fi diff --git a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 index 184b12b73..a14424f22 100644 --- a/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_UPLOAD_BUFFERSIZE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2018, 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_UPLOAD_BUFFERSIZE 3 "August 18, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_UPLOAD_BUFFERSIZE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_UPLOAD_BUFFERSIZE \- set preferred upload buffer size +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 @@ -43,7 +45,10 @@ allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is 16 kilobytes. Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle -isn't used for upload, this buffer will not be allocated at all. +is not used for upload, this buffer will not be 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 64 kB .SH PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3 index bb2916d9e..564bd6bd8 100644 --- a/docs/libcurl/opts/CURLOPT_URL.3 +++ b/docs/libcurl/opts/CURLOPT_URL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_URL 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_URL 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_URL \- provide the URL to use in the request +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 @@ -37,7 +39,7 @@ scheme://host:port/path For a greater explanation of the format please see RFC3986. -libcurl doesn't validate the syntax or use this variable until the transfer is +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 will still return \fICURLE_OK\fP. @@ -65,237 +67,6 @@ set. \fICURLOPT_URL(3)\fP or \fICURLOPT_CURLU(3)\fP \fBmust\fP be set before a transfer is started. -The host part of the URL contains the address of the server that you want to -connect to. This can be the fully qualified domain name of the server, the -local network name of the machine on your network or the IP address of the -server or machine represented by either an IPv4 or IPv6 address. For example: - -http://www.example.com/ - -http://hostname/ - -http://192.168.0.1/ - -http://[2001:1890:1112:1::20]/ - -It is also possible to specify the user name, password and any supported login -options as part of the host, for the following protocols, when connecting to -servers that require authentication: - -http://user:password@www.example.com - -ftp://user:password@ftp.example.com - -smb://domain%2fuser:password@server.example.com - -imap://user:password;options@mail.example.com - -pop3://user:password;options@mail.example.com - -smtp://user:password;options@mail.example.com - -At present only IMAP, POP3 and SMTP support login options as part of the host. -For more information about the login options in URL syntax please see RFC2384, -RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0). - -The port is optional and when not specified libcurl will use the default port -based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25 -for SMTP, etc. The following examples show how to specify the port: - -http://www.example.com:8080/ - This will connect to a web server using port -8080 rather than 80. - -smtp://mail.example.com:587/ - This will connect to a SMTP server on the -alternative mail port. - -The path part of the URL is protocol specific and whilst some examples are -given below this list is not conclusive: - -.IP HTTP -The path part of an HTTP request specifies the file to retrieve and from what -directory. If the directory is not specified then the web server's root -directory is used. If the file is omitted then the default document will be -retrieved for either the directory specified or the root directory. The exact -resource returned for each URL is entirely dependent on the server's -configuration. - -http://www.example.com - This gets the main page from the web server. - -http://www.example.com/index.html - This returns the main page by explicitly -requesting it. - -http://www.example.com/contactus/ - This returns the default document from -the contactus directory. - -.IP FTP -The path part of an FTP request specifies the file to retrieve and from what -directory. If the file part is omitted then libcurl downloads the directory -listing for the directory specified. If the directory is omitted then -the directory listing for the root / home directory will be returned. - -ftp://ftp.example.com - This retrieves the directory listing for the root -directory. - -ftp://ftp.example.com/readme.txt - This downloads the file readme.txt from the -root directory. - -ftp://ftp.example.com/libcurl/readme.txt - This downloads readme.txt from the -libcurl directory. - -ftp://user:password@ftp.example.com/readme.txt - This retrieves the readme.txt -file from the user's home directory. When a username and password is -specified, everything that is specified in the path part is relative to the -user's home directory. To retrieve files from the root directory or a -directory underneath the root directory then the absolute path must be -specified by prepending an additional forward slash to the beginning of the -path. - -ftp://user:password@ftp.example.com//readme.txt - This retrieves the readme.txt -from the root directory when logging in as a specified user. - -.IP FILE -When a FILE:// URL is accessed on Windows systems, it can be crafted in a way -so that Windows attempts to connect to a (remote) machine when curl wants to -read or write such a path. -.IP SMTP -The path part of a SMTP request specifies the host name to present during -communication with the mail server. If the path is omitted then libcurl will -attempt to resolve the local computer's host name. However, this may not -return the fully qualified domain name that is required by some mail servers -and specifying this path allows you to set an alternative name, such as -your machine's fully qualified domain name, which you might have obtained -from an external function such as gethostname or getaddrinfo. - -smtp://mail.example.com - This connects to the mail server at example.com and -sends your local computer's host name in the HELO / EHLO command. - -smtp://mail.example.com/client.example.com - This will send client.example.com in -the HELO / EHLO command to the mail server at example.com. - -.IP POP3 -The path part of a POP3 request specifies the message ID to retrieve. If the -ID is not specified then a list of waiting messages is returned instead. - -pop3://user:password@mail.example.com - This lists the available messages for -the user - -pop3://user:password@mail.example.com/1 - This retrieves the first message for -the user - -.IP IMAP -The path part of an IMAP request not only specifies the mailbox to list (Added -in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the -mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets -(Added in 7.37.0) of the message to fetch and to specify what messages to -search for (Added in 7.37.0). - -imap://user:password@mail.example.com - Performs a top level folder list - -imap://user:password@mail.example.com/INBOX - Performs a folder list on the -user's inbox - -imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox -and fetches message with uid = 1 - -imap://user:password@mail.example.com/INBOX/;MAILINDEX=1 - Selects the user's inbox -and fetches the first message in the mail box - -imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects -the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches -message 2 if it is - -imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the -user's inbox and fetches the text portion of message 3 - -imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects -the user's inbox and fetches the first 1024 octets of message 4 - -imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and -checks for NEW messages - -imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the -user's inbox and searches for messages containing "shadows" in the subject -line - -For more information about the individual components of an IMAP URL please -see RFC5092. - -.IP SCP -The path part of a SCP request specifies the file to retrieve and from what -directory. The file part may not be omitted. The file is taken as an absolute -path from the root directory on the server. To specify a path relative to the -user's home directory on the server, prepend ~/ to the path portion. If the -user name is not embedded in the URL, it can be set with the -\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. - -scp://user@example.com/etc/issue - This specifies the file /etc/issue - -scp://example.com/~/my-file - This specifies the file my-file in the -user's home directory on the server -.IP SFTP -The path part of a SFTP request specifies the file to retrieve and from what -directory. If the file part is omitted then libcurl downloads the directory -listing for the directory specified. If the path ends in a / then a directory -listing is returned instead of a file. If the path is omitted entirely then -the directory listing for the root / home directory will be returned. If the -user name is not embedded in the URL, it can be set with the -\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. - -sftp://user:password@example.com/etc/issue - This specifies the file -/etc/issue - -sftp://user@example.com/~/my-file - This specifies the file my-file in the -user's home directory - -sftp://ssh.example.com/~/Documents/ - This requests a directory listing -of the Documents directory under the user's home directory - -.IP SMB -The path part of a SMB request specifies the file to retrieve and from what -share and directory or the share to upload to and as such, may not be omitted. -If the user name is not embedded in the URL, it can be set with the -\fICURLOPT_USERPWD(3)\fP or \fICURLOPT_USERNAME(3)\fP option. If the user name -is embedded in the URL then it must contain the domain name and as such, the -backslash must be URL encoded as %2f. - -smb://server.example.com/files/issue - This specifies the file "issue" located -in the root of the "files" share - -smb://server.example.com/files/ -T issue - This specifies the file "issue" will -be uploaded to the root of the "files" share. - -curl supports SMB version 1 (only) -.IP LDAP -The path part of a LDAP request can be used to specify the: Distinguished -Name, Attributes, Scope, Filter and Extension for a LDAP search. Each field -is separated by a question mark and when that field is not required an empty -string with the question mark separator should be included. - -ldap://ldap.example.com/o=My%20Organisation - This will perform a LDAP search -with the DN as My Organisation. - -ldap://ldap.example.com/o=My%20Organisation?postalAddress - This will perform -the same search but will only return postalAddress attributes. - -ldap://ldap.example.com/?rootDomainNamingContext - This specifies an empty DN -and requests information about the rootDomainNamingContext attribute for an -Active Directory server. - -For more information about the individual components of a LDAP URL please -see RFC4516. -.IP RTMP -There's no official URL spec for RTMP so libcurl uses the URL syntax supported -by the underlying librtmp library. It has a syntax where it wants a -traditional URL, followed by a space and a series of space-separated -name=value pairs. - -While space is not typically a "legal" letter, libcurl accepts them. When a -user wants to pass in a '#' (hash) character it will be treated as a fragment -and get cut off by libcurl if provided literally. You will instead have to -escape it by providing it as backslash and its ASCII value in hexadecimal: -"\\23". - -.RS 0 The application does not have to keep the string around after setting this option. .SH ENCODING @@ -304,12 +75,12 @@ 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). +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 -There is no default URL. If this option isn't set, no transfer can be +There is no default URL. 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 @@ -320,8 +91,8 @@ 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 very -hard when accepting user provided URLs. +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 @@ -351,7 +122,7 @@ POP3 and SMTP were added in 7.31.0 Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient heap space. -Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so +Note that \fIcurl_easy_setopt(3)\fP will not actually parse the given string so given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or similar is called. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_USERAGENT.3 b/docs/libcurl/opts/CURLOPT_USERAGENT.3 index 06bf2a22b..d4fc53da4 100644 --- a/docs/libcurl/opts/CURLOPT_USERAGENT.3 +++ b/docs/libcurl/opts/CURLOPT_USERAGENT.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_USERAGENT 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_USERAGENT 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_USERAGENT \- set HTTP user-agent header +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 will be used to set the User-Agent: header in the HTTP request sent to the remote server. This diff --git a/docs/libcurl/opts/CURLOPT_USERNAME.3 b/docs/libcurl/opts/CURLOPT_USERNAME.3 index 89497e765..27370a1c5 100644 --- a/docs/libcurl/opts/CURLOPT_USERNAME.3 +++ b/docs/libcurl/opts/CURLOPT_USERNAME.3 @@ -9,7 +9,7 @@ .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,7 +20,7 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_USERNAME 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_USERNAME 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_USERNAME \- user name to use in authentication @@ -40,7 +40,7 @@ authentication. You should not use this option together with the (older) 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 don't then the initial part of the authentication +Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. When using NTLM, the user name can be specified simply as the user name diff --git a/docs/libcurl/opts/CURLOPT_USERPWD.3 b/docs/libcurl/opts/CURLOPT_USERPWD.3 index 2706bbf6d..8f7a5d575 100644 --- a/docs/libcurl/opts/CURLOPT_USERPWD.3 +++ b/docs/libcurl/opts/CURLOPT_USERPWD.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,21 +20,23 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_USERPWD 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_USERPWD 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME CURLOPT_USERPWD \- user name 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 * as parameter, pointing to a null-terminated login details string for the connection. The format of which is: [user name]:[password]. When using Kerberos V5 authentication with a Windows based server, you should specify the user name part with the domain name in order for the server to -successfully obtain a Kerberos Ticket. If you don't then the initial part of +successfully obtain a Kerberos Ticket. If you do not then the initial part of the authentication handshake may fail. When using NTLM, the user name can be specified simply as the user name diff --git a/docs/libcurl/opts/CURLOPT_USE_SSL.3 b/docs/libcurl/opts/CURLOPT_USE_SSL.3 index 8382a37f2..3b7baea88 100644 --- a/docs/libcurl/opts/CURLOPT_USE_SSL.3 +++ b/docs/libcurl/opts/CURLOPT_USE_SSL.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_USE_SSL 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_USE_SSL 3 "November 30, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .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. @@ -37,9 +39,10 @@ using the STARTTLS command. This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc. .IP CURLUSESSL_NONE -Don't attempt to use SSL. +do not attempt to use SSL. .IP CURLUSESSL_TRY -Try using SSL, proceed as normal otherwise. +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 @@ -47,7 +50,7 @@ Require SSL for all communication or fail with \fICURLE_USE_SSL_FAILED\fP. .SH DEFAULT CURLUSESSL_NONE .SH PROTOCOLS -FTP, SMTP, POP3, IMAP +FTP, SMTP, POP3, IMAP, LDAP .SH EXAMPLE .nf CURL *curl = curl_easy_init(); @@ -64,6 +67,7 @@ if(curl) { .SH AVAILABILITY Added in 7.11.0. This option was known as CURLOPT_FTP_SSL up to 7.16.4, and the constants were known as CURLFTPSSL_* +Handled by LDAP since 7.81.0. Fully supported by the openldap backend only. .SH RETURN VALUE Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.3 b/docs/libcurl/opts/CURLOPT_VERBOSE.3 index 8b307c178..ee5b38d1a 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.3 +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,17 +20,19 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_VERBOSE 3 "September 16, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_VERBOSE 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_VERBOSE \- set verbose mode on/off +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. Very useful for +verbose information about its operations on this \fIhandle\fP. Useful for libcurl and/or protocol debugging and understanding. The verbose information will be sent to stderr, or the stream set with \fICURLOPT_STDERR(3)\fP. diff --git a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 index b90fca6a8..fd6551072 100644 --- a/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 +++ b/docs/libcurl/opts/CURLOPT_WILDCARDMATCH.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_WILDCARDMATCH 3 "May 18, 2018" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_WILDCARDMATCH 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_WILDCARDMATCH \- enable directory wildcard transfers +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 file name pattern. The pattern can be specified as part of the @@ -79,7 +81,21 @@ Using the rules above, a file name pattern can be constructed: .SH PROTOCOLS This feature is only supported for FTP download. .SH EXAMPLE -See https://curl.haxx.se/libcurl/c/ftp-wildcard.html +.nf + /* initialization of easy handle */ + handle = curl_easy_init(); + + /* turn on wildcard matching */ + curl_easy_setopt(handle, CURLOPT_WILDCARDMATCH, 1L); + + /* callback is called before download of concrete file started */ + curl_easy_setopt(handle, CURLOPT_CHUNK_BGN_FUNCTION, file_is_coming); + + /* callback is called after data from the file have been transferred */ + curl_easy_setopt(handle, CURLOPT_CHUNK_END_FUNCTION, file_is_downloaded); + + /* See more on https://curl.se/libcurl/c/ftp-wildcard.html */ +.fi .SH AVAILABILITY Added in 7.21.0 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 index f6b6764db..ed82ef186 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEDATA.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEDATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,25 +20,27 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_WRITEDATA 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_WRITEDATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_WRITEDATA \- custom pointer passed to the write callback +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'll get in that -callback's 4th argument. If you don't use a write callback, you must make +\fICURLOPT_WRITEFUNCTION(3)\fP option, this is the pointer you will get in that +callback's 4th argument. If you do not use a write callback, you must make \fIpointer\fP a 'FILE *' (cast to 'void *') as libcurl will pass this to \fIfwrite(3)\fP when writing data. The internal \fICURLOPT_WRITEFUNCTION(3)\fP will write the data to the FILE * -given with this option, or to stdout if this option hasn't been set. +given with this option, or to stdout if this option has not been set. -If you're using libcurl as a win32 DLL, you \fBMUST\fP use a +If you are using libcurl as a win32 DLL, you \fBMUST\fP use a \fICURLOPT_WRITEFUNCTION(3)\fP if you set this option or you will experience crashes. .SH DEFAULT @@ -50,7 +52,7 @@ 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 getinmemory example: -https://curl.haxx.se/libcurl/c/getinmemory.html +https://curl.se/libcurl/c/getinmemory.html .SH AVAILABILITY Available in all libcurl versions. This option was formerly known as \fICURLOPT_FILE\fP, the name \fICURLOPT_WRITEDATA(3)\fP was introduced in diff --git a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 index 3156c8f7b..3ffe72262 100644 --- a/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_WRITEFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,10 +20,10 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_WRITEFUNCTION 3 "August 24, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_WRITEFUNCTION 3 "October 31, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_WRITEFUNCTION \- set callback for writing received data +CURLOPT_WRITEFUNCTION \- callback for writing received data .SH SYNOPSIS .nf #include <curl/curl.h> @@ -58,7 +58,7 @@ The data passed to this function will not be null-terminated! 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'll +that amount differs from the amount passed to your callback function, it will signal an error condition to the library. This will cause the transfer to get aborted and the libcurl function used will return \fICURLE_WRITE_ERROR\fP. @@ -68,14 +68,13 @@ transfer to become paused. 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 will write 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 libcurl will use 'fwrite' as a callback by default. .SH PROTOCOLS For all protocols -.SH AVAILABILITY -Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. -.SH RETURN VALUE -This will return CURLE_OK. .SH EXAMPLE .nf struct memory { @@ -100,7 +99,7 @@ This will return CURLE_OK. return realsize; } - struct memory chunk; + struct memory chunk = {0}; /* send all data to this function */ curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, cb); @@ -108,6 +107,10 @@ This will return CURLE_OK. /* we pass our 'chunk' struct to the callback function */ curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)&chunk); .fi +.SH AVAILABILITY +Support for the CURL_WRITEFUNC_PAUSE return code was added in version 7.18.0. +.SH RETURN VALUE +This will return CURLE_OK. .SH "SEE ALSO" .BR CURLOPT_WRITEDATA "(3), " CURLOPT_READFUNCTION "(3), " .BR CURLOPT_HEADERFUNCTION "(3), " diff --git a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 index 16789321c..a9ff6d5ab 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 +++ b/docs/libcurl/opts/CURLOPT_XFERINFODATA.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_XFERINFODATA 3 "October 09, 2017" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_XFERINFODATA 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_XFERINFODATA \- custom pointer passed to the progress callback +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 will be untouched by libcurl and passed as the first argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION(3)\fP. @@ -38,7 +40,32 @@ The default value of this parameter is NULL. .SH PROTOCOLS All .SH EXAMPLE -https://curl.haxx.se/libcurl/c/progressfunc.html +.nf + struct progress { + char *private; + size_t size; + }; + + static size_t progress_callback(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow) + { + struct memory *progress = (struct progress *)userp; + + /* use the values */ + + return 0; /* all is good */ + } + + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data); + + curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback); +.fi .SH AVAILABILITY Added in 7.32.0 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 index 0deb566de..d262abf0c 100644 --- a/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 +++ b/docs/libcurl/opts/CURLOPT_XFERINFOFUNCTION.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,11 +20,12 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_XFERINFOFUNCTION 3 "March 23, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_XFERINFOFUNCTION 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_XFERINFOFUNCTION \- callback to progress meter function +CURLOPT_XFERINFOFUNCTION \- progress meter callback .SH SYNOPSIS +.nf #include <curl/curl.h> int progress_callback(void *clientp, @@ -33,13 +34,15 @@ int progress_callback(void *clientp, curl_off_t ultotal, curl_off_t ulnow); -CURLcode curl_easy_setopt(CURL *handle, CURLOPT_XFERINFOFUNCTION, progress_callback); +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 will be called very +frequent interval. While data is being transferred it will be called frequently, and during slow periods like when nothing is being transferred it can slow down to about one call per second. @@ -71,12 +74,37 @@ function that performs transfers. \fICURLOPT_NOPROGRESS(3)\fP must be set to 0 to make this function actually get called. .SH DEFAULT -By default, libcurl has an internal progress meter. That's rarely wanted by +By default, libcurl has an internal progress meter. That is rarely wanted by users. .SH PROTOCOLS All .SH EXAMPLE -https://curl.haxx.se/libcurl/c/progressfunc.html +.nf + struct progress { + char *private; + size_t size; + }; + + static size_t progress_callback(void *clientp, + curl_off_t dltotal, + curl_off_t dlnow, + curl_off_t ultotal, + curl_off_t ulnow) + { + struct memory *progress = (struct progress *)userp; + + /* use the values */ + + return 0; /* all is good */ + } + + struct progress data; + + /* pass struct to callback */ + curl_easy_setopt(curl_handle, CURLOPT_XFERINFODATA, &data); + + curl_easy_setopt(curl_handle, CURLOPT_XFERINFOFUNCTION, progress_callback); +.fi .SH AVAILABILITY Added in 7.32.0. This callback replaces \fICURLOPT_PROGRESSFUNCTION(3)\fP .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 index bbdfb9f00..e4c10daed 100644 --- a/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 +++ b/docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.3 @@ -5,11 +5,11 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms -.\" * are also available at https://curl.haxx.se/docs/copyright.html. +.\" * are also available at https://curl.se/docs/copyright.html. .\" * .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell .\" * copies of the Software, and permit persons to whom the Software is @@ -20,14 +20,16 @@ .\" * .\" ************************************************************************** .\" -.TH CURLOPT_XOAUTH2_BEARER 3 "June 25, 2020" "libcurl 7.73.0" "curl_easy_setopt options" +.TH CURLOPT_XOAUTH2_BEARER 3 "November 26, 2021" "libcurl 7.81.0" "curl_easy_setopt options" .SH NAME -CURLOPT_XOAUTH2_BEARER \- specify OAuth 2.0 access token +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 * as parameter, which should point to the null-terminated OAuth 2.0 Bearer Access Token for use with HTTP, IMAP, POP3 and SMTP servers diff --git a/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 new file mode 100644 index 000000000..ac50a1dc5 --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_LOCKFUNC.3 @@ -0,0 +1,71 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH CURLSHOPT_LOCKFUNC 3 "November 12, 2021" "libcurl 7.81.0" "libcurl Manual" + +.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 *userptr); + +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's a corresponding +\fICURLSHOPT_UNLOCKFUNC(3)\fP callback called when the mutex is again relased. + +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. + +\fIuserptr\fP is the private pointer you set with \fICURLSHOPT_USERDATA\fP. +This pointer is not used by libcurl itself. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf + CURLSHcode sh + 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 7.10 +.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_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/opts/CURLSHOPT_SHARE.3 b/docs/libcurl/opts/CURLSHOPT_SHARE.3 new file mode 100644 index 000000000..90c6eedc1 --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_SHARE.3 @@ -0,0 +1,98 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH CURLSHOPT_SHARE 3 "November 12, 2021" "libcurl 7.81.0" "libcurl Manual" + +.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 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 will be shared across the easy handles using this shared object. +Note that this does not activate an easy handle's cookie handling. You can do +that separately by using \fICURLOPT_COOKIEFILE(3)\fP for example. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts will be 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 will share DNS cache by default without using this +option. +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs will be shared across the easy handles using this shared +object. This will reduce the time spent in the SSL handshake when reconnecting +to the same server. Note SSL session IDs are reused within the same easy +handle by default. Note this symbol was added in 7.10.3 but was not +implemented until 7.23.0. +.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. + +Note that due to a known bug, it is not safe to share connections this way +between multiple concurrent threads. + +Connections that are used for HTTP/1.1 Pipelining or HTTP/2 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 HTTP/2 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 will share 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 will share PSL cache by default without using this option. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf + CURLSHcode sh + 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 7.10 +.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_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 new file mode 100644 index 000000000..00bc4907e --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_UNLOCKFUNC.3 @@ -0,0 +1,70 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH CURLSHOPT_UNLOCKFUNC 3 "November 12, 2021" "libcurl 7.81.0" "libcurl Manual" + +.SH NAME +CURLSHOPT_UNLOCKFUNC - mutex unlock callback +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +void unlockcb(CURL *handle, curl_lock_data data, curl_lock_access access, + void *userptr); + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_UNLOCKFUNC, unlockcb); +.fi +.SH DESCRIPTION +Set a mutex unlock callback for the share object. There's 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. + +\fIaccess\fP defines what access type libcurl wants, shared or single. + +\fIuserptr\fP is the private pointer you set with \fICURLSHOPT_USERDATA\fP. +This pointer is not used by libcurl itself. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf + CURLSHcode sh + 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 7.10 +.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_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 new file mode 100644 index 000000000..2d8a2cdf9 --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_UNSHARE.3 @@ -0,0 +1,71 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH CURLSHOPT_UNSHARE 3 "November 12, 2021" "libcurl 7.81.0" "libcurl Manual" + +.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 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 will no longer be shared across the easy handles using this shared +object. +.IP CURL_LOCK_DATA_DNS +Cached DNS hosts will be no longer be shared across the easy handles using +this shared object. +.IP CURL_LOCK_DATA_SSL_SESSION +SSL session IDs will no longer be 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 +All +.SH EXAMPLE +.nf + CURLSHcode sh + 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 7.10 +.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_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/opts/CURLSHOPT_USERDATA.3 b/docs/libcurl/opts/CURLSHOPT_USERDATA.3 new file mode 100644 index 000000000..77f98422b --- /dev/null +++ b/docs/libcurl/opts/CURLSHOPT_USERDATA.3 @@ -0,0 +1,55 @@ +.\" ************************************************************************** +.\" * _ _ ____ _ +.\" * Project ___| | | | _ \| | +.\" * / __| | | | |_) | | +.\" * | (__| |_| | _ <| |___ +.\" * \___|\___/|_| \_\_____| +.\" * +.\" * Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * +.\" * This software is licensed as described in the file COPYING, which +.\" * you should have received as part of this distribution. The terms +.\" * are also available at https://curl.se/docs/copyright.html. +.\" * +.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell +.\" * copies of the Software, and permit persons to whom the Software is +.\" * furnished to do so, under the terms of the COPYING file. +.\" * +.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY +.\" * KIND, either express or implied. +.\" * +.\" ************************************************************************** +.TH CURLSHOPT_USERDATA 3 "December 09, 2021" "libcurl 7.81.0" "libcurl Manual" + +.SH NAME +CURLSHOPT_USERDATA - pointer passed to the (un)lock mutex callbacks +.SH SYNOPSIS +.nf +#include <curl/curl.h> + +CURLSHcode curl_share_setopt(CURLSH *share, CURLSHOPT_USERDATA, void *ptr); +.fi +.SH DESCRIPTION +The \fIptr\fP parameter is held verbatim by libcurl and is passed on as the +\fIuserptr\fP argument to the callbacks set with \fICURLSHOPT_LOCKFUNC(3)\fP +and \fICURLSHOPT_UNLOCKFUNC(3)\fP. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf + CURLSHcode sh + struct secrets private_stuff; + 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 7.10 +.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_setopt "(3), " curl_share_cleanup "(3), " curl_share_init "(3)" diff --git a/docs/libcurl/opts/Makefile.am b/docs/libcurl/opts/Makefile.am index 3765ea7bf..6596ae357 100644 --- a/docs/libcurl/opts/Makefile.am +++ b/docs/libcurl/opts/Makefile.am @@ -5,11 +5,11 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms -# are also available at https://curl.haxx.se/docs/copyright.html. +# are also available at https://curl.se/docs/copyright.html. # # You may opt to use, copy, modify, merge, publish, distribute and/or sell # copies of the Software, and permit persons to whom the Software is diff --git a/docs/libcurl/opts/Makefile.in b/docs/libcurl/opts/Makefile.in index 45deb3c96..63fa5aa3a 100644 --- a/docs/libcurl/opts/Makefile.in +++ b/docs/libcurl/opts/Makefile.in @@ -1,7 +1,7 @@ -# Makefile.in generated by automake 1.16.2 from Makefile.am. +# Makefile.in generated by automake 1.16.5 from Makefile.am. # @configure_input@ -# Copyright (C) 1994-2020 Free Software Foundation, Inc. +# Copyright (C) 1994-2021 Free Software Foundation, Inc. # This Makefile.in is free software; the Free Software Foundation # gives unlimited permission to copy and/or distribute it, @@ -21,11 +21,11 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms -# are also available at https://curl.haxx.se/docs/copyright.html. +# are also available at https://curl.se/docs/copyright.html. # # You may opt to use, copy, modify, merge, publish, distribute and/or sell # copies of the Software, and permit persons to whom the Software is @@ -43,11 +43,11 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms -# are also available at https://curl.haxx.se/docs/copyright.html. +# are also available at https://curl.se/docs/copyright.html. # # You may opt to use, copy, modify, merge, publish, distribute and/or sell # copies of the Software, and permit persons to whom the Software is @@ -135,12 +135,22 @@ host_triplet = @host@ subdir = docs/libcurl/opts ACLOCAL_M4 = $(top_srcdir)/aclocal.m4 am__aclocal_m4_deps = $(top_srcdir)/m4/ax_compile_check_sizeof.m4 \ + $(top_srcdir)/m4/curl-amissl.m4 \ + $(top_srcdir)/m4/curl-bearssl.m4 \ $(top_srcdir)/m4/curl-compilers.m4 \ $(top_srcdir)/m4/curl-confopts.m4 \ $(top_srcdir)/m4/curl-functions.m4 \ + $(top_srcdir)/m4/curl-gnutls.m4 \ + $(top_srcdir)/m4/curl-mbedtls.m4 \ + $(top_srcdir)/m4/curl-mesalink.m4 $(top_srcdir)/m4/curl-nss.m4 \ $(top_srcdir)/m4/curl-openssl.m4 \ $(top_srcdir)/m4/curl-override.m4 \ - $(top_srcdir)/m4/curl-reentrant.m4 $(top_srcdir)/m4/libtool.m4 \ + $(top_srcdir)/m4/curl-reentrant.m4 \ + $(top_srcdir)/m4/curl-rustls.m4 \ + $(top_srcdir)/m4/curl-schannel.m4 \ + $(top_srcdir)/m4/curl-sectransp.m4 \ + $(top_srcdir)/m4/curl-sysconfig.m4 \ + $(top_srcdir)/m4/curl-wolfssl.m4 $(top_srcdir)/m4/libtool.m4 \ $(top_srcdir)/m4/ltoptions.m4 $(top_srcdir)/m4/ltsugar.m4 \ $(top_srcdir)/m4/ltversion.m4 $(top_srcdir)/m4/lt~obsolete.m4 \ $(top_srcdir)/m4/xc-am-iface.m4 \ @@ -232,6 +242,8 @@ CONFIGURE_OPTIONS = @CONFIGURE_OPTIONS@ CPP = @CPP@ CPPFLAGS = @CPPFLAGS@ CPPFLAG_CURL_STATICLIB = @CPPFLAG_CURL_STATICLIB@ +CSCOPE = @CSCOPE@ +CTAGS = @CTAGS@ CURLVERSION = @CURLVERSION@ CURL_CA_BUNDLE = @CURL_CA_BUNDLE@ CURL_CFLAG_EXTRAS = @CURL_CFLAG_EXTRAS@ @@ -268,6 +280,7 @@ ECHO_T = @ECHO_T@ EGREP = @EGREP@ ENABLE_SHARED = @ENABLE_SHARED@ ENABLE_STATIC = @ENABLE_STATIC@ +ETAGS = @ETAGS@ EXEEXT = @EXEEXT@ FGREP = @FGREP@ FISH_FUNCTIONS_DIR = @FISH_FUNCTIONS_DIR@ @@ -292,9 +305,6 @@ LD = @LD@ LDFLAGS = @LDFLAGS@ LIBCURL_LIBS = @LIBCURL_LIBS@ LIBCURL_NO_SHARED = @LIBCURL_NO_SHARED@ -LIBMETALINK_CPPFLAGS = @LIBMETALINK_CPPFLAGS@ -LIBMETALINK_LDFLAGS = @LIBMETALINK_LDFLAGS@ -LIBMETALINK_LIBS = @LIBMETALINK_LIBS@ LIBOBJS = @LIBOBJS@ LIBS = @LIBS@ LIBTOOL = @LIBTOOL@ @@ -343,7 +353,7 @@ SUPPORT_PROTOCOLS = @SUPPORT_PROTOCOLS@ USE_ARES = @USE_ARES@ USE_BEARSSL = @USE_BEARSSL@ USE_GNUTLS = @USE_GNUTLS@ -USE_GNUTLS_NETTLE = @USE_GNUTLS_NETTLE@ +USE_HYPER = @USE_HYPER@ USE_LIBRTMP = @USE_LIBRTMP@ USE_LIBSSH = @USE_LIBSSH@ USE_LIBSSH2 = @USE_LIBSSH2@ @@ -357,9 +367,13 @@ USE_NGTCP2_CRYPTO_OPENSSL = @USE_NGTCP2_CRYPTO_OPENSSL@ USE_NSS = @USE_NSS@ USE_OPENLDAP = @USE_OPENLDAP@ USE_QUICHE = @USE_QUICHE@ +USE_RUSTLS = @USE_RUSTLS@ USE_SCHANNEL = @USE_SCHANNEL@ USE_SECTRANSP = @USE_SECTRANSP@ USE_UNIX_SOCKETS = @USE_UNIX_SOCKETS@ +USE_WIN32_CRYPTO = @USE_WIN32_CRYPTO@ +USE_WIN32_LARGE_FILES = @USE_WIN32_LARGE_FILES@ +USE_WIN32_SMALL_FILES = @USE_WIN32_SMALL_FILES@ USE_WINDOWS_SSPI = @USE_WINDOWS_SSPI@ USE_WOLFSSH = @USE_WOLFSSH@ USE_WOLFSSL = @USE_WOLFSSL@ @@ -466,6 +480,7 @@ man_MANS = \ CURLINFO_REDIRECT_TIME.3 \ CURLINFO_REDIRECT_TIME_T.3 \ CURLINFO_REDIRECT_URL.3 \ + CURLINFO_REFERER.3 \ CURLINFO_REQUEST_SIZE.3 \ CURLINFO_RESPONSE_CODE.3 \ CURLINFO_RETRY_AFTER.3 \ @@ -516,6 +531,7 @@ man_MANS = \ CURLOPT_AUTOREFERER.3 \ CURLOPT_BUFFERSIZE.3 \ CURLOPT_CAINFO.3 \ + CURLOPT_CAINFO_BLOB.3 \ CURLOPT_CAPATH.3 \ CURLOPT_CERTINFO.3 \ CURLOPT_CHUNK_BGN_FUNCTION.3 \ @@ -552,6 +568,9 @@ man_MANS = \ CURLOPT_DNS_SERVERS.3 \ CURLOPT_DNS_SHUFFLE_ADDRESSES.3 \ CURLOPT_DNS_USE_GLOBAL_CACHE.3 \ + CURLOPT_DOH_SSL_VERIFYHOST.3 \ + CURLOPT_DOH_SSL_VERIFYPEER.3 \ + CURLOPT_DOH_SSL_VERIFYSTATUS.3 \ CURLOPT_DOH_URL.3 \ CURLOPT_EGDSOCKET.3 \ CURLOPT_ERRORBUFFER.3 \ @@ -582,6 +601,12 @@ man_MANS = \ CURLOPT_HEADERDATA.3 \ CURLOPT_HEADERFUNCTION.3 \ CURLOPT_HEADEROPT.3 \ + CURLOPT_HSTS.3 \ + CURLOPT_HSTSREADDATA.3 \ + CURLOPT_HSTSREADFUNCTION.3 \ + CURLOPT_HSTSWRITEDATA.3 \ + CURLOPT_HSTSWRITEFUNCTION.3 \ + CURLOPT_HSTS_CTRL.3 \ CURLOPT_HTTP09_ALLOWED.3 \ CURLOPT_HTTP200ALIASES.3 \ CURLOPT_HTTPAUTH.3 \ @@ -619,10 +644,12 @@ man_MANS = \ CURLOPT_MAXCONNECTS.3 \ CURLOPT_MAXFILESIZE.3 \ CURLOPT_MAXFILESIZE_LARGE.3 \ + CURLOPT_MAXLIFETIME_CONN.3 \ CURLOPT_MAXREDIRS.3 \ CURLOPT_MAX_RECV_SPEED_LARGE.3 \ CURLOPT_MAX_SEND_SPEED_LARGE.3 \ CURLOPT_MIMEPOST.3 \ + CURLOPT_MIME_OPTIONS.3 \ CURLOPT_NETRC.3 \ CURLOPT_NETRC_FILE.3 \ CURLOPT_NEW_DIRECTORY_PERMS.3 \ @@ -645,6 +672,8 @@ man_MANS = \ CURLOPT_POSTQUOTE.3 \ CURLOPT_POSTREDIR.3 \ CURLOPT_PREQUOTE.3 \ + CURLOPT_PREREQDATA.3 \ + CURLOPT_PREREQFUNCTION.3 \ CURLOPT_PRE_PROXY.3 \ CURLOPT_PRIVATE.3 \ CURLOPT_PROGRESSDATA.3 \ @@ -659,6 +688,7 @@ man_MANS = \ CURLOPT_PROXYUSERNAME.3 \ CURLOPT_PROXYUSERPWD.3 \ CURLOPT_PROXY_CAINFO.3 \ + CURLOPT_PROXY_CAINFO_BLOB.3 \ CURLOPT_PROXY_CAPATH.3 \ CURLOPT_PROXY_CRLFILE.3 \ CURLOPT_PROXY_KEYPASSWD.3 \ @@ -716,6 +746,7 @@ man_MANS = \ CURLOPT_SSH_AUTH_TYPES.3 \ CURLOPT_SSH_COMPRESSION.3 \ CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 \ + CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 \ CURLOPT_SSH_KEYDATA.3 \ CURLOPT_SSH_KEYFUNCTION.3 \ CURLOPT_SSH_KNOWNHOSTS.3 \ @@ -778,13 +809,19 @@ man_MANS = \ CURLOPT_USERNAME.3 \ CURLOPT_USERPWD.3 \ CURLOPT_USE_SSL.3 \ + CURLOPT_AWS_SIGV4.3 \ CURLOPT_VERBOSE.3 \ CURLOPT_WILDCARDMATCH.3 \ CURLOPT_WRITEDATA.3 \ CURLOPT_WRITEFUNCTION.3 \ CURLOPT_XFERINFODATA.3 \ CURLOPT_XFERINFOFUNCTION.3 \ - CURLOPT_XOAUTH2_BEARER.3 + CURLOPT_XOAUTH2_BEARER.3 \ + CURLSHOPT_LOCKFUNC.3 \ + CURLSHOPT_SHARE.3 \ + CURLSHOPT_UNLOCKFUNC.3 \ + CURLSHOPT_UNSHARE.3 \ + CURLSHOPT_USERDATA.3 man_DISTMANS = $(man_MANS:.3=.3.dist) HTMLPAGES = $(man_MANS:.3=.html) @@ -882,7 +919,6 @@ ctags CTAGS: cscope cscopelist: - distdir: $(BUILT_SOURCES) $(MAKE) $(AM_MAKEFLAGS) distdir-am diff --git a/docs/libcurl/opts/Makefile.inc b/docs/libcurl/opts/Makefile.inc index fe4177579..5a270a8a9 100644 --- a/docs/libcurl/opts/Makefile.inc +++ b/docs/libcurl/opts/Makefile.inc @@ -5,11 +5,11 @@ # | (__| |_| | _ <| |___ # \___|\___/|_| \_\_____| # -# Copyright (C) 1998 - 2020, Daniel Stenberg, <daniel@haxx.se>, et al. +# Copyright (C) 1998 - 2021, Daniel Stenberg, <daniel@haxx.se>, et al. # # This software is licensed as described in the file COPYING, which # you should have received as part of this distribution. The terms -# are also available at https://curl.haxx.se/docs/copyright.html. +# are also available at https://curl.se/docs/copyright.html. # # You may opt to use, copy, modify, merge, publish, distribute and/or sell # copies of the Software, and permit persons to whom the Software is @@ -64,6 +64,7 @@ man_MANS = \ CURLINFO_REDIRECT_TIME.3 \ CURLINFO_REDIRECT_TIME_T.3 \ CURLINFO_REDIRECT_URL.3 \ + CURLINFO_REFERER.3 \ CURLINFO_REQUEST_SIZE.3 \ CURLINFO_RESPONSE_CODE.3 \ CURLINFO_RETRY_AFTER.3 \ @@ -114,6 +115,7 @@ man_MANS = \ CURLOPT_AUTOREFERER.3 \ CURLOPT_BUFFERSIZE.3 \ CURLOPT_CAINFO.3 \ + CURLOPT_CAINFO_BLOB.3 \ CURLOPT_CAPATH.3 \ CURLOPT_CERTINFO.3 \ CURLOPT_CHUNK_BGN_FUNCTION.3 \ @@ -150,6 +152,9 @@ man_MANS = \ CURLOPT_DNS_SERVERS.3 \ CURLOPT_DNS_SHUFFLE_ADDRESSES.3 \ CURLOPT_DNS_USE_GLOBAL_CACHE.3 \ + CURLOPT_DOH_SSL_VERIFYHOST.3 \ + CURLOPT_DOH_SSL_VERIFYPEER.3 \ + CURLOPT_DOH_SSL_VERIFYSTATUS.3 \ CURLOPT_DOH_URL.3 \ CURLOPT_EGDSOCKET.3 \ CURLOPT_ERRORBUFFER.3 \ @@ -180,6 +185,12 @@ man_MANS = \ CURLOPT_HEADERDATA.3 \ CURLOPT_HEADERFUNCTION.3 \ CURLOPT_HEADEROPT.3 \ + CURLOPT_HSTS.3 \ + CURLOPT_HSTSREADDATA.3 \ + CURLOPT_HSTSREADFUNCTION.3 \ + CURLOPT_HSTSWRITEDATA.3 \ + CURLOPT_HSTSWRITEFUNCTION.3 \ + CURLOPT_HSTS_CTRL.3 \ CURLOPT_HTTP09_ALLOWED.3 \ CURLOPT_HTTP200ALIASES.3 \ CURLOPT_HTTPAUTH.3 \ @@ -217,10 +228,12 @@ man_MANS = \ CURLOPT_MAXCONNECTS.3 \ CURLOPT_MAXFILESIZE.3 \ CURLOPT_MAXFILESIZE_LARGE.3 \ + CURLOPT_MAXLIFETIME_CONN.3 \ CURLOPT_MAXREDIRS.3 \ CURLOPT_MAX_RECV_SPEED_LARGE.3 \ CURLOPT_MAX_SEND_SPEED_LARGE.3 \ CURLOPT_MIMEPOST.3 \ + CURLOPT_MIME_OPTIONS.3 \ CURLOPT_NETRC.3 \ CURLOPT_NETRC_FILE.3 \ CURLOPT_NEW_DIRECTORY_PERMS.3 \ @@ -243,6 +256,8 @@ man_MANS = \ CURLOPT_POSTQUOTE.3 \ CURLOPT_POSTREDIR.3 \ CURLOPT_PREQUOTE.3 \ + CURLOPT_PREREQDATA.3 \ + CURLOPT_PREREQFUNCTION.3 \ CURLOPT_PRE_PROXY.3 \ CURLOPT_PRIVATE.3 \ CURLOPT_PROGRESSDATA.3 \ @@ -257,6 +272,7 @@ man_MANS = \ CURLOPT_PROXYUSERNAME.3 \ CURLOPT_PROXYUSERPWD.3 \ CURLOPT_PROXY_CAINFO.3 \ + CURLOPT_PROXY_CAINFO_BLOB.3 \ CURLOPT_PROXY_CAPATH.3 \ CURLOPT_PROXY_CRLFILE.3 \ CURLOPT_PROXY_KEYPASSWD.3 \ @@ -314,6 +330,7 @@ man_MANS = \ CURLOPT_SSH_AUTH_TYPES.3 \ CURLOPT_SSH_COMPRESSION.3 \ CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.3 \ + CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.3 \ CURLOPT_SSH_KEYDATA.3 \ CURLOPT_SSH_KEYFUNCTION.3 \ CURLOPT_SSH_KNOWNHOSTS.3 \ @@ -376,10 +393,16 @@ man_MANS = \ CURLOPT_USERNAME.3 \ CURLOPT_USERPWD.3 \ CURLOPT_USE_SSL.3 \ + CURLOPT_AWS_SIGV4.3 \ CURLOPT_VERBOSE.3 \ CURLOPT_WILDCARDMATCH.3 \ CURLOPT_WRITEDATA.3 \ CURLOPT_WRITEFUNCTION.3 \ CURLOPT_XFERINFODATA.3 \ CURLOPT_XFERINFOFUNCTION.3 \ - CURLOPT_XOAUTH2_BEARER.3 + CURLOPT_XOAUTH2_BEARER.3 \ + CURLSHOPT_LOCKFUNC.3 \ + CURLSHOPT_SHARE.3 \ + CURLSHOPT_UNLOCKFUNC.3 \ + CURLSHOPT_UNSHARE.3 \ + CURLSHOPT_USERDATA.3 |