docs/libcurl/opts/CURLOPT_ACCEPT_ENCODING.md+13 -10
| @@ -42,19 +42,19 @@ built-in supported encodings. |
| |
| Alternatively, you can specify exactly the encoding or list of encodings you |
| want in the response. The following encodings are supported: *identity*, |
| - | meaning non-compressed, *deflate* which requests the server to compress |
| - | its response using the zlib algorithm, *gzip* which requests the gzip |
| - | algorithm, (since curl 7.57.0) *br* which is brotli and (since curl |
| - | 7.72.0) *zstd* which is zstd. Provide them in the string as a |
| - | comma-separated list of accepted encodings, like: **"br, gzip, deflate"**. |
| - | |
| - | Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which |
| - | makes libcurl not send an Accept-Encoding: header and not decompress received |
| + | meaning non-compressed, *deflate* which requests the server to compress its |
| + | response using the zlib algorithm, *gzip* which requests the gzip algorithm, |
| + | (since curl 7.57.0) *br* which is brotli and (since curl 7.72.0) *zstd* which |
| + | is zstd. Provide them in the string as a comma-separated list of accepted |
| + | encodings, like: **"br, gzip, deflate"**. |
| + | |
| + | Set CURLOPT_ACCEPT_ENCODING(3) to NULL to explicitly disable it, which makes |
| + | libcurl not send an Accept-Encoding: header and not decompress received |
| contents automatically. |
| |
| You can also opt to just include the Accept-Encoding: header in your request |
| - | with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing |
| - | when receiving data. |
| + | with CURLOPT_HTTPHEADER(3) but then there is no automatic decompressing when |
| + | receiving data. |
| |
| This is a request, not an order; the server may or may not do it. This option |
| must be set (to any non-NULL value) or else any unsolicited encoding done by |
| @@ -72,6 +72,9 @@ sending the length of the non-compressed content is a common server mistake). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. |
| + | |
| # HISTORY |
| |
| This option was called CURLOPT_ENCODING before 7.21.6 |
docs/libcurl/opts/CURLOPT_ALTSVC.md+6 -0
| @@ -35,6 +35,12 @@ CURLOPT_ALTSVC_CTRL(3). |
| |
| Specify a blank filename ("") to make libcurl not load from a file at all. |
| |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL. The alt-svc cache is not read nor written to file. |
docs/libcurl/opts/CURLOPT_AWS_SIGV4.md+6 -0
| @@ -68,6 +68,12 @@ generated string. |
| Setting CURLOPT_HTTPAUTH(3) with the CURLAUTH_AWS_SIGV4 bit set is the same as |
| setting this option with a **"aws:amz"** parameter. |
| |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_CAINFO.md+3 -0
| @@ -54,6 +54,9 @@ store of root certificates (the default for Schannel). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| The default value for this can be figured out with CURLINFO_CAINFO(3). |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_CAPATH.md+3 -0
| @@ -45,6 +45,9 @@ to some limitation in OpenSSL. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| The default value for this can be figured out with CURLINFO_CAPATH(3). |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_CONNECT_TO.md+3 -0
| @@ -76,6 +76,9 @@ When this option is passed to curl_easy_setopt(3), libcurl does not copy the |
| list so you **must** keep it around until you no longer use this *handle* for |
| a transfer before you call curl_slist_free_all(3) on the list. |
| |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_COOKIE.md+4 -4
| @@ -54,15 +54,15 @@ Since this custom cookie is appended to the Cookie: header in addition to any |
| cookies set by the cookie engine, there is a risk that the header ends up too |
| long and thereby getting the entire request rejected by the server. |
| |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| Using this option multiple times makes the last set string override the |
| - | previous ones. |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| This option does not enable the cookie engine. Use CURLOPT_COOKIEFILE(3) or |
| CURLOPT_COOKIEJAR(3) to enable parsing and sending cookies automatically. |
| |
| - | The application does not have to keep the string around after setting this |
| - | option. |
| - | |
| # DEFAULT |
| |
| NULL, no cookies |
docs/libcurl/opts/CURLOPT_COOKIEFILE.md+3 -5
| @@ -48,14 +48,12 @@ domain cannot match the target URL's. To address this, set a domain in |
| Set-Cookie line (doing that includes subdomains) or preferably: use the |
| Netscape format. |
| |
| - | If you use this option multiple times, you add more files to read cookies |
| - | from. |
| - | |
| The application does not have to keep the string around after setting this |
| option. |
| |
| - | Setting this option to NULL (since 7.77.0) explicitly disables the cookie |
| - | engine and clears the list of files to read cookies from. |
| + | If you use this option multiple times, you add more files to read cookies |
| + | from. Setting this option to NULL disables the cookie engine and clears the |
| + | list of files to read cookies from. |
| |
| # SECURITY |
| |
docs/libcurl/opts/CURLOPT_COOKIEJAR.md+13 -11
| @@ -27,22 +27,21 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COOKIEJAR, char *filename); |
| |
| # DESCRIPTION |
| |
| - | Pass a *filename* as a char *, null-terminated. This makes libcurl write |
| - | all internally known cookies to the specified file when |
| - | curl_easy_cleanup(3) is called. If no cookies are kept in memory at that |
| - | time, no file is created. Specify "-" as filename to instead have the cookies |
| - | written to stdout. Using this option also enables cookies for this session, so |
| - | if you for example follow a redirect it makes matching cookies get sent |
| - | accordingly. |
| + | Pass a *filename* as a char *, null-terminated. This makes libcurl write all |
| + | internally known cookies to the specified file when curl_easy_cleanup(3) is |
| + | called. If no cookies are kept in memory at that time, no file is created. |
| + | Specify "-" as filename to instead have the cookies written to stdout. Using |
| + | this option also enables cookies for this session, so if you for example |
| + | follow a redirect it makes matching cookies get sent accordingly. |
| |
| Note that libcurl does not read any cookies from the cookie jar specified with |
| this option. To read cookies from a file, use CURLOPT_COOKIEFILE(3). |
| |
| If the cookie jar file cannot be created or written to (when the |
| - | curl_easy_cleanup(3) is called), libcurl does not and cannot report an |
| - | error for this. Using CURLOPT_VERBOSE(3) or |
| - | CURLOPT_DEBUGFUNCTION(3) displays a warning, but that is the only |
| - | visible feedback you get about this possibly lethal situation. |
| + | curl_easy_cleanup(3) is called), libcurl does not and cannot report an error |
| + | for this. Using CURLOPT_VERBOSE(3) or CURLOPT_DEBUGFUNCTION(3) displays a |
| + | warning, but that is the only visible feedback you get about this possibly |
| + | lethal situation. |
| |
| Cookies are imported in the Set-Cookie format without a domain name are not |
| exported by this option. |
| @@ -50,6 +49,9 @@ exported by this option. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.md+13 -8
| @@ -33,14 +33,19 @@ HTTP POST operation. It behaves as the CURLOPT_POSTFIELDS(3) option, but the |
| original data is instead copied by the library, allowing the application to |
| overwrite the original data after setting this option. |
| |
| - | Because data are copied, care must be taken when using this option in |
| - | conjunction with CURLOPT_POSTFIELDSIZE(3) or |
| - | CURLOPT_POSTFIELDSIZE_LARGE(3): If the size has not been set prior to |
| - | CURLOPT_COPYPOSTFIELDS(3), the data is assumed to be a null-terminated |
| - | string; else the stored size informs the library about the byte count to |
| - | copy. In any case, the size must not be changed after |
| - | CURLOPT_COPYPOSTFIELDS(3), unless another CURLOPT_POSTFIELDS(3) or |
| - | CURLOPT_COPYPOSTFIELDS(3) option is issued. |
| + | Because data is copied, care must be taken when using this option in |
| + | conjunction with CURLOPT_POSTFIELDSIZE(3) or CURLOPT_POSTFIELDSIZE_LARGE(3). |
| + | If the size has not been set prior to CURLOPT_COPYPOSTFIELDS(3), the data is |
| + | assumed to be a null-terminated string; else the stored size informs the |
| + | library about the byte count to copy. In any case, the size must not be |
| + | changed after CURLOPT_COPYPOSTFIELDS(3), unless another CURLOPT_POSTFIELDS(3) |
| + | or CURLOPT_COPYPOSTFIELDS(3) option is set. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_CRLFILE.md+6 -3
| @@ -49,13 +49,16 @@ This option makes sense only when used in combination with the |
| CURLOPT_SSL_VERIFYPEER(3) option. |
| |
| A specific error code (*CURLE_SSL_CRL_BADFILE*) is defined with the option. It |
| - | is returned when the SSL exchange fails because the CRL file cannot be |
| - | loaded. A failure in certificate verification due to a revocation information |
| - | found in the CRL does not trigger this specific error. |
| + | is returned when the SSL exchange fails because the CRL file cannot be loaded. |
| + | A failure in certificate verification due to a revocation information found in |
| + | the CRL does not trigger this specific error. |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_CUSTOMREQUEST.md+7 -3
| @@ -34,14 +34,18 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_CUSTOMREQUEST, char *method); |
| |
| Pass a pointer to a null-terminated string as parameter. |
| |
| - | When changing the request *method* by setting CURLOPT_CUSTOMREQUEST(3), you |
| - | do not actually change how libcurl behaves or acts: you only change the actual |
| + | When changing the request *method* by setting CURLOPT_CUSTOMREQUEST(3), you do |
| + | not actually change how libcurl behaves or acts: you only change the actual |
| string sent in the request. |
| |
| libcurl passes on the verbatim string in its request without any filter or |
| other safe guards. That includes white space and control characters. |
| |
| - | Restore to the internal default by setting this to NULL. |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Restore to the internal default by setting this to NULL. |
| |
| This option can be used to specify the request: |
| |
docs/libcurl/opts/CURLOPT_DEFAULT_PROTOCOL.md+9 -6
| @@ -37,12 +37,12 @@ Use one of these protocol (scheme) names: |
| dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, |
| pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp |
| |
| - | An unknown or unsupported protocol causes error |
| - | *CURLE_UNSUPPORTED_PROTOCOL* when libcurl parses a URL without a |
| - | scheme. Parsing happens when curl_easy_perform(3) or |
| - | curl_multi_perform(3) is called. The protocol set supported by libcurl |
| - | vary depending on how it was built. Use curl_version_info(3) if you need |
| - | a list of protocol names supported by the build of libcurl that you are using. |
| + | An unknown or unsupported protocol causes error *CURLE_UNSUPPORTED_PROTOCOL* |
| + | when libcurl parses a URL without a scheme. Parsing happens when |
| + | curl_easy_perform(3) or curl_multi_perform(3) is called. The protocol set |
| + | supported by libcurl vary depending on how it was built. Use |
| + | curl_version_info(3) if you need a list of protocol names supported by the |
| + | build of libcurl that you are using. |
| |
| This option does not change the default proxy protocol (http). |
| |
| @@ -52,6 +52,9 @@ CURLOPT_URL(3) for details. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL (make a guess based on the host) |
docs/libcurl/opts/CURLOPT_DNS_INTERFACE.md+3 -0
| @@ -36,6 +36,9 @@ specific interface). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP4.md+3 -0
| @@ -35,6 +35,9 @@ specific IP address). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_DNS_LOCAL_IP6.md+3 -0
| @@ -35,6 +35,9 @@ address). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_DNS_SERVERS.md+5 -2
| @@ -30,15 +30,18 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DNS_SERVERS, char *servers); |
| Pass a char pointer that is the list of DNS servers to be used instead of the |
| system default. The format of the dns servers option is: |
| |
| - | host[:port][,host[:port]]... |
| + | host[:port][,host[:port]]... |
| |
| For example: |
| |
| - | 192.168.1.100,192.168.1.101,3.4.5.6 |
| + | 192.168.1.100,192.168.1.101,3.4.5.6 |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_DOH_URL.md+5 -1
| @@ -41,7 +41,11 @@ To find the DoH server itself, which might be specified using a name, libcurl |
| uses the default name lookup function. You can bootstrap that by providing the |
| address for the DoH server with CURLOPT_RESOLVE(3). |
| |
| - | Disable DoH use again by setting this option to NULL. |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| # INHERIT OPTIONS |
| |
docs/libcurl/opts/CURLOPT_ECH.md+8 -0
| @@ -70,6 +70,14 @@ If the string starts with `pn:` then the remainder of the string should be a |
| DNS/hostname that is used to over-ride the public_name field of the |
| ECHConfigList that is used for ECH. |
| |
| + | ## |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL or "false" to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, meaning ECH is disabled. |
docs/libcurl/opts/CURLOPT_ERRORBUFFER.md+7 -4
| @@ -37,16 +37,19 @@ be at least **CURL_ERROR_SIZE** bytes big. |
| |
| You must keep the associated buffer available until libcurl no longer needs |
| it. Failing to do so might cause odd behavior or even crashes. libcurl might |
| - | need it until you call curl_easy_cleanup(3) or you set the same option |
| - | again to use a different pointer. |
| + | need it until you call curl_easy_cleanup(3) or you set the same option again |
| + | to use a different pointer. |
| |
| Do not rely on the contents of the buffer unless an error code was returned. |
| Since 7.60.0 libcurl initializes the contents of the error buffer to an empty |
| string before performing the transfer. For earlier versions if an error code |
| was returned but there was no error detail then the buffer was untouched. |
| |
| - | Consider CURLOPT_VERBOSE(3) and CURLOPT_DEBUGFUNCTION(3) to better |
| - | debug and trace why errors happen. |
| + | Consider CURLOPT_VERBOSE(3) and CURLOPT_DEBUGFUNCTION(3) to better debug and |
| + | trace why errors happen. |
| + | |
| + | Using this option multiple times makes the last set pointer override the |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_FTPPORT.md+8 -9
| @@ -46,12 +46,10 @@ specifier can be in brackets. |
| |
| Examples with specified ports: |
| |
| - | ~~~c |
| - | eth0:0 |
| - | 192.168.1.2:32000-33000 |
| - | curl.se:32123 |
| - | [::1]:1234-4567 |
| - | ~~~ |
| + | eth0:0 |
| + | 192.168.1.2:32000-33000 |
| + | curl.se:32123 |
| + | [::1]:1234-4567 |
| |
| We strongly advise against specifying the address with a name, as it causes |
| libcurl to do a blocking name resolve call to retrieve the IP address. That |
| @@ -61,12 +59,13 @@ CURLOPT_DOH_URL(3) is set. |
| Using anything else than "-" for this option should typically only be done if |
| you have special knowledge and confirmation that it works. |
| |
| - | You disable PORT again and go back to using the passive version by setting |
| - | this option to NULL. |
| - | |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. You disable PORT again and go back to using the passive version |
| + | by setting this option to NULL. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_FTP_ACCOUNT.md+3 -0
| @@ -33,6 +33,9 @@ this data is sent off using the ACCT command. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_HAPROXY_CLIENT_IP.md+8 -2
| @@ -31,8 +31,14 @@ When this parameter is set to a valid IPv4 or IPv6 numerical address, the |
| library sends this address as client address in the HAProxy PROXY protocol v1 |
| header at beginning of the connection. |
| |
| - | This option is an alternative to CURLOPT_HAPROXYPROTOCOL(3) as that one |
| - | cannot use a specified address. |
| + | This option is an alternative to CURLOPT_HAPROXYPROTOCOL(3) as that one cannot |
| + | use a specified address. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_HSTS.md+4 -3
| @@ -33,8 +33,9 @@ name with this option also enables HSTS for this handle (the equivalent of |
| setting *CURLHSTS_ENABLE* with CURLOPT_HSTS_CTRL(3)). |
| |
| If the given file does not exist or contains no HSTS entries at startup, the |
| - | HSTS cache simply starts empty. Setting the filename to NULL or "" only |
| - | enables HSTS without reading from or writing to any file. |
| + | HSTS cache simply starts empty. Setting the filename to NULL allows HSTS |
| + | without reading from or writing to any file. NULL also makes libcurl clear the |
| + | list of files to read HSTS data from, if any such were previously set. |
| |
| If this option is set multiple times, libcurl loads cache entries from each |
| given file but only stores the last used name for later writing. |
| @@ -44,7 +45,7 @@ given file but only stores the last used name for later writing. |
| 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] [stamp] |
| |
| [host] is the domain name for the entry and the name is dot-prefixed if it is |
| an entry valid for all subdomains to the name as well or only for the exact |
docs/libcurl/opts/CURLOPT_HTTP200ALIASES.md+6 -0
| @@ -41,6 +41,12 @@ curl_slist_free_all(3) to clean up an entire list. |
| The alias itself is not parsed for any version strings. The protocol is |
| assumed to match HTTP 1.0 when an alias match. |
| |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_HTTPHEADER.md+19 -20
| @@ -39,19 +39,18 @@ requests! |
| |
| When used within an IMAP or SMTP request to upload a MIME mail, the given |
| header list establishes the document-level MIME headers to prepend to the |
| - | uploaded document described by CURLOPT_MIMEPOST(3). This does not affect |
| - | raw mail uploads. |
| - | |
| - | The linked list should be a fully valid list of **struct curl_slist** |
| - | structs properly filled in. Use curl_slist_append(3) to create the list |
| - | and curl_slist_free_all(3) to clean up an entire list. If you add a |
| - | header that is otherwise generated and used by libcurl internally, your added |
| - | header is used instead. If you add a header with no content as in 'Accept:' |
| - | (no data on the right side of the colon), the internally used header is |
| - | disabled/removed. With this option you can add new headers, replace internal |
| - | headers and remove internal headers. To add a header with no content (nothing |
| - | to the right side of the colon), use the form 'name;' (note the ending |
| - | semicolon). |
| + | uploaded document described by CURLOPT_MIMEPOST(3). This does not affect raw |
| + | mail uploads. |
| + | |
| + | The linked list should be a fully valid list of **struct curl_slist** structs |
| + | properly filled in. Use curl_slist_append(3) to create the list and |
| + | curl_slist_free_all(3) to clean up an entire list. If you add a header that is |
| + | otherwise generated and used by libcurl internally, your added header is used |
| + | instead. If you add a header with no content as in 'Accept:' (no data on the |
| + | right side of the colon), the internally used header is disabled/removed. With |
| + | this option you can add new headers, replace internal headers and remove |
| + | internal headers. To add a header with no content (nothing to the right side |
| + | of the colon), use the form 'name;' (note the ending semicolon). |
| |
| The headers included in the linked list **must not** be CRLF-terminated, |
| because libcurl adds CRLF after each header item itself. Failure to comply |
| @@ -65,16 +64,16 @@ following the request-line are headers. Adding this method line in this list |
| of headers only causes your request to send an invalid header. Use |
| CURLOPT_CUSTOMREQUEST(3) to change the method. |
| |
| - | When this option is passed to curl_easy_setopt(3), libcurl does not copy |
| - | the entire list so you **must** keep it around until you no longer use this |
| - | *handle* for a transfer before you call curl_slist_free_all(3) on |
| - | the list. |
| + | When this option is passed to curl_easy_setopt(3), libcurl does not copy the |
| + | entire list so you **must** keep it around until you no longer use this |
| + | *handle* for a transfer before you call curl_slist_free_all(3) on the list. |
| |
| - | Pass a NULL to this option to reset back to no custom headers. |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| |
| The most commonly replaced HTTP headers have "shortcuts" in the options |
| - | CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3) and |
| - | CURLOPT_REFERER(3). We recommend using those. |
| + | CURLOPT_COOKIE(3), CURLOPT_USERAGENT(3) and CURLOPT_REFERER(3). We recommend |
| + | using those. |
| |
| There is an alternative option that sets or replaces headers only for requests |
| that are sent with CONNECT to a proxy: CURLOPT_PROXYHEADER(3). Use |
docs/libcurl/opts/CURLOPT_INTERFACE.md+5 -2
| @@ -44,13 +44,16 @@ libcurl does not support using network interface names for this option on |
| Windows. |
| |
| We strongly advise against specifying the interface with a hostname, as it |
| - | causes libcurl to do a blocking name resolve call to retrieve the IP |
| - | address. That name resolve operation does **not** use DNS-over-HTTPS even if |
| + | causes libcurl to do a blocking name resolve call to retrieve the IP address. |
| + | That name resolve operation does **not** use DNS-over-HTTPS even if |
| CURLOPT_DOH_URL(3) is set. |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, use whatever the TCP stack finds suitable |
docs/libcurl/opts/CURLOPT_ISSUERCERT.md+3 -0
| @@ -46,6 +46,9 @@ which is returned if the setup of the SSL/TLS session has failed due to a |
| mismatch with the issuer of peer certificate (CURLOPT_SSL_VERIFYPEER(3) |
| has to be set too for the check to fail). (Added in 7.19.0) |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| The application does not have to keep the string around after setting this |
| option. |
| |
docs/libcurl/opts/CURLOPT_KEYPASSWD.md+3 -0
| @@ -39,6 +39,9 @@ load a certificate but you need one to load your private key. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_KRBLEVEL.md+3 -0
| @@ -35,6 +35,9 @@ string to NULL to disable kerberos support for FTP. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_LOGIN_OPTIONS.md+3 -0
| @@ -48,6 +48,9 @@ disables the plain LOGIN (e.g. to prevent password snooping). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_MAIL_AUTH.md+3 -0
| @@ -45,6 +45,9 @@ string is used then a pair of brackets are sent by libcurl as required by RFC |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_MAIL_FROM.md+3 -0
| @@ -38,6 +38,9 @@ server which might cause the email to be rejected. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| blank |
docs/libcurl/opts/CURLOPT_MAIL_RCPT.md+6 -0
| @@ -32,6 +32,9 @@ SMTP mail request. The linked list should be a fully valid list of |
| **struct curl_slist** structs properly filled in. Use curl_slist_append(3) to |
| create the list and curl_slist_free_all(3) to clean up an entire list. |
| |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| + | |
| When performing a mail transfer, each recipient should be specified within a |
| pair of angled brackets (\<\>), however, should you not use an angled bracket |
| as the first character libcurl assumes you provided a single email address and |
| @@ -45,6 +48,9 @@ When performing a mailing list expand (**EXPN** command), each recipient |
| should be specified using the mailing list name, such as `Friends` or |
| `London-Office`. |
| |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_NETRC_FILE.md+3 -0
| @@ -35,6 +35,9 @@ for a .netrc file in the current user's home directory. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_NOPROXY.md+4 -1
| @@ -41,7 +41,7 @@ proxy for all hostnames, even if there is an environment variable set for it. |
| Enter IPv6 numerical addresses in the list of hostnames without enclosing |
| brackets: |
| |
| - | "example.com,::1,localhost" |
| + | "example.com,::1,localhost" |
| |
| Since 7.86.0, IP addresses specified to this option can be provided using CIDR |
| notation: an appended slash and number specifies the number of "network bits" |
| @@ -51,6 +51,9 @@ would match all addresses starting with "192.168". |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # Environment variables |
| |
| If there is an environment variable called **no_proxy** (or **NO_PROXY**), |
docs/libcurl/opts/CURLOPT_PASSWORD.md+3 -0
| @@ -37,6 +37,9 @@ CURLOPT_USERNAME(3) option. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| blank |
docs/libcurl/opts/CURLOPT_POSTFIELDS.md+9 -7
| @@ -41,10 +41,9 @@ preserved by the calling application until the associated transfer finishes. |
| This behavior can be changed (so libcurl does copy the data) by instead using |
| the CURLOPT_COPYPOSTFIELDS(3) option. |
| |
| - | This POST is a normal **application/x-www-form-urlencoded** kind (and |
| - | libcurl sets that Content-Type by default when this option is used), which is |
| - | commonly used by HTML forms. Change Content-Type with |
| - | CURLOPT_HTTPHEADER(3). |
| + | This POST is a normal **application/x-www-form-urlencoded** kind (and libcurl |
| + | sets that Content-Type by default when this option is used), which is commonly |
| + | used by HTML forms. Change Content-Type with CURLOPT_HTTPHEADER(3). |
| |
| You can use curl_easy_escape(3) to URL encode your data, if |
| necessary. It returns a pointer to an encoded string that can be passed as |
| @@ -58,9 +57,9 @@ CURLOPT_POSTFIELDS(3) to an empty string, or set CURLOPT_POST(3) to 1 and |
| CURLOPT_POSTFIELDSIZE(3) to 0. |
| |
| libcurl assumes this option points to a null-terminated string unless you also |
| - | set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, |
| - | which then is strictly required if you want to send off null bytes included in |
| - | the data. |
| + | set CURLOPT_POSTFIELDSIZE(3) to specify the length of the provided data, which |
| + | then is strictly required if you want to send off null bytes included in the |
| + | data. |
| |
| Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header, |
| and libcurl adds that header automatically if the POST is either known to be |
| @@ -70,6 +69,9 @@ header with CURLOPT_HTTPHEADER(3) as usual. |
| To make **multipart/formdata** posts, check out the |
| CURLOPT_MIMEPOST(3) option combined with curl_mime_init(3). |
| |
| + | Using this option multiple times makes the last set pointer override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_POSTQUOTE.md+6 -1
| @@ -33,7 +33,11 @@ after your FTP transfer request. The commands are only issued if no error |
| occur. The linked list should be a fully valid list of struct curl_slist |
| structs properly filled in as described for CURLOPT_QUOTE(3). |
| |
| - | Disable this operation again by setting a NULL to this option. |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| |
| # DEFAULT |
| |
| @@ -62,6 +66,7 @@ int main(void) |
| |
| curl_easy_cleanup(curl); |
| } |
| + | curl_slist_free_all(cmdlist); |
| } |
| ~~~ |
| |
docs/libcurl/opts/CURLOPT_PREQUOTE.md+8 -2
| @@ -30,8 +30,13 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PREQUOTE, |
| Pass a pointer to a linked list of FTP commands to pass to the server after |
| the transfer type is set. The linked list should be a fully valid list of |
| struct curl_slist structs properly filled in as described for |
| - | CURLOPT_QUOTE(3). Disable this operation again by setting a NULL to this |
| - | option. |
| + | CURLOPT_QUOTE(3). |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| |
| These commands are not performed when a directory listing is performed, only |
| for file transfers. |
| @@ -65,6 +70,7 @@ int main(void) |
| |
| curl_easy_cleanup(curl); |
| } |
| + | curl_slist_free_all(cmdlist); |
| } |
| ~~~ |
| |
docs/libcurl/opts/CURLOPT_PRE_PROXY.md+3 -0
| @@ -54,6 +54,9 @@ single port number used widely for proxies. Specify it. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROTOCOLS_STR.md+6 -3
| @@ -49,9 +49,12 @@ You can set "ALL" as a short-cut to enable all protocols. Note that by setting |
| all, you may enable protocols that were not supported the day you write this |
| but are introduced in a future libcurl version. |
| |
| - | curl_version_info(3) can be used to get a list of all supported |
| - | protocols in the current libcurl. CURLINFO_SCHEME(3) is the recommended |
| - | way to figure out the protocol used in a previous transfer. |
| + | curl_version_info(3) can be used to get a list of all supported protocols in |
| + | the current libcurl. CURLINFO_SCHEME(3) is the recommended way to figure out |
| + | the protocol used in a previous transfer. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to the internal default. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_PROXY.md+6 -0
| @@ -41,6 +41,12 @@ defaults to using port 1080 for proxies. |
| The proxy string may be prefixed with [scheme]:// to specify which kind of |
| proxy is used. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| ## http:// |
| |
| HTTP Proxy. Default when no scheme or proxy type is specified. |
docs/libcurl/opts/CURLOPT_PROXYHEADER.md+5 -1
| @@ -39,7 +39,11 @@ NOT a header and cannot be replaced using this option. Only the lines |
| following the request-line are headers. Adding this method line in this list |
| of headers causes your request to send an invalid header. |
| |
| - | Pass a NULL to this to reset back to no custom headers. |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_PROXYPASSWORD.md+7 -4
| @@ -28,15 +28,18 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXYPASSWORD, char *pwd); |
| |
| # DESCRIPTION |
| |
| - | Pass a char pointer as parameter, which should be pointing to the null-terminated |
| - | password to use for authentication with the proxy. |
| + | Pass a char pointer as parameter, which should be pointing to the |
| + | null-terminated password to use for authentication with the proxy. |
| |
| - | The CURLOPT_PROXYPASSWORD(3) option should be used in conjunction with |
| - | the CURLOPT_PROXYUSERNAME(3) option. |
| + | The CURLOPT_PROXYPASSWORD(3) option should be used in conjunction with the |
| + | CURLOPT_PROXYUSERNAME(3) option. |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| blank |
docs/libcurl/opts/CURLOPT_PROXYUSERPWD.md+3 -0
| @@ -39,6 +39,9 @@ Use CURLOPT_PROXYAUTH(3) to specify the authentication method. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_CAINFO.md+4 -0
| @@ -56,6 +56,10 @@ method of verifying the peer's certificate chain. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again and switches back to |
| + | internal default. |
| + | |
| The default value for this can be figured out with CURLINFO_CAINFO(3). |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_PROXY_CAPATH.md+4 -0
| @@ -42,6 +42,10 @@ CURLOPT_PROXY_SSL_VERIFYPEER(3) is enabled (which it is by default). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again and switch back to |
| + | internal default. |
| + | |
| The default value for this can be figured out with CURLINFO_CAPATH(3). |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_PROXY_CRLFILE.md+3 -0
| @@ -55,6 +55,9 @@ the CRL does not trigger this specific error. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_ISSUERCERT.md+7 -5
| @@ -40,18 +40,20 @@ additional check is useful in multi-level PKI where one needs to enforce that |
| the peer certificate is from a specific branch of the tree. |
| |
| This option makes sense only when used in combination with the |
| - | CURLOPT_PROXY_SSL_VERIFYPEER(3) option. Otherwise, the result of the |
| - | check is not considered as failure. |
| + | CURLOPT_PROXY_SSL_VERIFYPEER(3) option. Otherwise, the result of the check is |
| + | not considered as failure. |
| |
| A specific error code (CURLE_SSL_ISSUER_ERROR) is defined with the option, |
| which is returned if the setup of the SSL/TLS session has failed due to a |
| - | mismatch with the issuer of peer certificate |
| - | (CURLOPT_PROXY_SSL_VERIFYPEER(3) has to be set too for the check to |
| - | fail). |
| + | mismatch with the issuer of peer certificate (CURLOPT_PROXY_SSL_VERIFYPEER(3) |
| + | has to be set too for the check to fail). |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_KEYPASSWD.md+3 -0
| @@ -43,6 +43,9 @@ key. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_PINNEDPUBLICKEY.md+3 -0
| @@ -50,6 +50,9 @@ On mismatch, *CURLE_SSL_PINNEDPUBKEYNOTMATCH* is returned. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_SERVICE_NAME.md+3 -0
| @@ -35,6 +35,9 @@ service. The default service name is **"HTTP"** for HTTP based proxies and |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| See above |
docs/libcurl/opts/CURLOPT_PROXY_SSLCERT.md+3 -0
| @@ -52,6 +52,9 @@ private key with CURLOPT_PROXY_SSLKEY(3). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_SSLCERTTYPE.md+3 -0
| @@ -45,6 +45,9 @@ files. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| "PEM" |
docs/libcurl/opts/CURLOPT_PROXY_SSLKEY.md+3 -0
| @@ -46,6 +46,9 @@ present in the key chain or PKCS#12 file containing the certificate. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_SSLKEYTYPE.md+3 -0
| @@ -39,6 +39,9 @@ the format of your private key. Supported formats are "PEM", "DER" and "ENG". |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # %PROTOCOLS% |
| |
| # EXAMPLE |
docs/libcurl/opts/CURLOPT_PROXY_SSL_CIPHER_LIST.md+4 -1
| @@ -46,7 +46,7 @@ strings separated by colons. |
| For setting TLS 1.3 ciphers see CURLOPT_PROXY_TLS13_CIPHERS(3). |
| |
| A valid example of a cipher list is: |
| - | ~~~c |
| + | ~~~ |
| "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" |
| "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" |
| ~~~ |
| @@ -61,6 +61,9 @@ Find more details about cipher lists on this URL: |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, use internal built-in list. |
docs/libcurl/opts/CURLOPT_PROXY_TLS13_CIPHERS.md+4 -1
| @@ -44,7 +44,7 @@ separated by colons. |
| For setting TLS 1.2 (1.1, 1.0) ciphers see CURLOPT_PROXY_SSL_CIPHER_LIST(3). |
| |
| A valid example of a cipher list is: |
| - | ~~~c |
| + | ~~~ |
| "TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256" |
| ~~~ |
| |
| @@ -55,6 +55,9 @@ Find more details about cipher lists on this URL: |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, use internal built-in list |
docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_PASSWORD.md+3 -0
| @@ -40,6 +40,9 @@ CURLOPT_PROXY_TLSAUTH_USERNAME(3) option also be set. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_TYPE.md+6 -0
| @@ -36,6 +36,12 @@ Pass a pointer to a null-terminated string as parameter. The string should be |
| the method of the TLS authentication used for the HTTPS connection. Supported |
| method is "SRP". |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to internal default. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| ## SRP |
| |
| TLS-SRP authentication. Secure Remote Password authentication for TLS is |
docs/libcurl/opts/CURLOPT_PROXY_TLSAUTH_USERNAME.md+3 -0
| @@ -40,6 +40,9 @@ CURLOPT_PROXY_TLSAUTH_PASSWORD(3) option also be set. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_QUOTE.md+5 -1
| @@ -37,7 +37,9 @@ of 'struct curl_slist' structs properly filled in with text strings. Use |
| curl_slist_append(3) to append strings (commands) to the list, and clear |
| the entire list afterwards with curl_slist_free_all(3). |
| |
| - | Disable this operation again by setting a NULL to this option. |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. libcurl does not copy the list, |
| + | it needs to be kept around until after the transfer has completed. |
| |
| When speaking to an FTP server, prefix the command with an asterisk (*) to |
| make libcurl continue even if the command fails as by default libcurl stops at |
| @@ -151,6 +153,8 @@ int main(void) |
| |
| curl_easy_cleanup(curl); |
| } |
| + | |
| + | curl_slist_free_all(cmdlist); |
| } |
| ~~~ |
| |
docs/libcurl/opts/CURLOPT_RANGE.md+2 -1
| @@ -50,7 +50,8 @@ RTSP, byte ranges are **not** permitted. Instead, ranges should be given in |
| For HTTP PUT uploads this option should not be used, since it may conflict with |
| other options. |
| |
| - | Pass a NULL to this option to disable the use of ranges. |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| The application does not have to keep the string around after setting this |
| option. |
docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS_STR.md+8 -2
| @@ -33,8 +33,8 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_REDIR_PROTOCOLS_STR, |
| Pass a pointer to a string that holds a comma-separated list of case |
| insensitive protocol names (URL schemes). That list limits what protocols |
| libcurl may use in a transfer that it follows to in a redirect when |
| - | CURLOPT_FOLLOWLOCATION(3) is enabled. This option allows applications to |
| - | limit specific transfers to only be allowed to use a subset of protocols in |
| + | CURLOPT_FOLLOWLOCATION(3) is enabled. This option allows applications to limit |
| + | specific transfers to only be allowed to use a subset of protocols in |
| redirections. |
| |
| Protocols denied by CURLOPT_PROTOCOLS_STR(3) are not overridden by this |
| @@ -56,6 +56,12 @@ but are introduced in a future libcurl version. |
| If trying to set a non-existing protocol or if no matching protocol at all is |
| set, it returns error. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to internal default. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| # DEFAULT |
| |
| HTTP, HTTPS, FTP and FTPS (Added in 7.65.2). |
docs/libcurl/opts/CURLOPT_REFERER.md+3 -0
| @@ -35,6 +35,9 @@ set any custom header with CURLOPT_HTTPHEADER(3). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_REQUEST_TARGET.md+6 -0
| @@ -34,6 +34,12 @@ instead of the path as extracted from the URL. |
| libcurl passes on the verbatim string in its request without any filter or |
| other safe guards. That includes white space and control characters. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_RESOLVE.md+8 -6
| @@ -34,11 +34,12 @@ list of **struct curl_slist** structs properly filled in. Use |
| curl_slist_append(3) to create the list and curl_slist_free_all(3) to clean up |
| an entire list. |
| |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| + | |
| Each resolve rule to add should be written using the format |
| |
| - | ~~~c |
| - | [+]HOST:PORT:ADDRESS[,ADDRESS] |
| - | ~~~ |
| + | [+]HOST:PORT:ADDRESS[,ADDRESS] |
| |
| HOST is the name libcurl wants to resolve, PORT is the port number of the |
| service where libcurl wants to connect to the HOST and ADDRESS is one or more |
| @@ -67,13 +68,14 @@ setting of CURLOPT_IPRESOLVE(3) to a different IP version. |
| To remove names from the DNS cache again, to stop providing these fake |
| resolves, include a string in the linked list that uses the format |
| |
| - | ~~~ |
| - | -HOST:PORT |
| - | ~~~ |
| + | -HOST:PORT |
| |
| The entry to remove must be prefixed with a dash, and the hostname and port |
| number must exactly match what was added previously. |
| |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_RTSP_SESSION_ID.md+3 -0
| @@ -36,6 +36,9 @@ server sets it in a response. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md+3 -0
| @@ -40,6 +40,9 @@ to. (e.g. the CURLOPT_URL(3) for the above examples might be set to |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| "*" |
docs/libcurl/opts/CURLOPT_SASL_AUTHZID.md+14 -8
| @@ -31,14 +31,20 @@ Pass a char pointer as parameter, which should be pointing to the |
| null-terminated authorization identity (*authzid*) for the transfer. Only |
| applicable to the PLAIN SASL authentication mechanism where it is optional. |
| |
| - | When not specified only the authentication identity (*authcid*) as |
| - | specified by the username is sent to the server, along with the password. The |
| - | server derives a *authzid* from the *authcid* when not provided, which |
| - | it then uses internally. |
| - | |
| - | When the *authzid* is specified, the use of which is server dependent, it |
| - | can be used to access another user's inbox, that the user has been granted |
| - | access to, or a shared mailbox for example. |
| + | When not specified only the authentication identity (*authcid*) as specified |
| + | by the username is sent to the server, along with the password. The server |
| + | derives a *authzid* from the *authcid* when not provided, which it then uses |
| + | internally. |
| + | |
| + | When the *authzid* is specified, the use of which is server dependent, it can |
| + | be used to access another user's inbox, that the user has been granted access |
| + | to, or a shared mailbox for example. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_SERVICE_NAME.md+3 -0
| @@ -40,6 +40,9 @@ allows you to change them. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| See above |
docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_MD5.md+3 -0
| @@ -40,6 +40,9 @@ CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256(3) instead. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSH_HOST_PUBLIC_KEY_SHA256.md+6 -0
| @@ -33,6 +33,12 @@ Pass a char pointer pointing to a string containing a Base64-encoded SHA256 |
| hash of the remote host's public key. The transfer fails if the given hash |
| does not match the hash the remote host provides. |
| |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSH_KNOWNHOSTS.md+3 -0
| @@ -37,6 +37,9 @@ behavior on host and key matches and mismatches. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSLCERT.md+9 -7
| @@ -48,13 +48,12 @@ in order to avoid confusion with a nickname. |
| certificate store. (You can import *PFX* to a store first). You can use |
| "\<store location\>\\\<store name\>\\\<thumbprint\>" to refer to a certificate |
| in the system certificates store, for example, |
| - | **"CurrentUser\\MY\\934a7ac6f8a5d579285a74fa"**. The thumbprint is usually a |
| - | SHA-1 hex string which you can see in certificate details. Following store |
| - | locations are supported: **CurrentUser**, **LocalMachine**, |
| - | **CurrentService**, **Services**, **CurrentUserGroupPolicy**, |
| - | **LocalMachineGroupPolicy**, **LocalMachineEnterprise**. Schannel also support |
| - | P12 certificate file, with the string `P12` specified with |
| - | CURLOPT_SSLCERTTYPE(3). |
| + | **"CurrentUser\\MY\\934a7ac6f8a5d5"**. The thumbprint is usually a SHA-1 hex |
| + | string which you can see in certificate details. Following store locations are |
| + | supported: **CurrentUser**, **LocalMachine**, **CurrentService**, |
| + | **Services**, **CurrentUserGroupPolicy**, **LocalMachineGroupPolicy**, |
| + | **LocalMachineEnterprise**. Schannel also support P12 certificate file, with |
| + | the string `P12` specified with CURLOPT_SSLCERTTYPE(3). |
| |
| When using a client certificate, you most likely also need to provide a |
| private key with CURLOPT_SSLKEY(3). |
| @@ -62,6 +61,9 @@ private key with CURLOPT_SSLKEY(3). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSLCERTTYPE.md+3 -0
| @@ -44,6 +44,9 @@ files. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL restores back to internal default. |
| + | |
| # DEFAULT |
| |
| "PEM" |
docs/libcurl/opts/CURLOPT_SSLENGINE.md+3 -0
| @@ -35,6 +35,9 @@ identifier for the crypto engine you want to use for your private key. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSLKEY.md+3 -0
| @@ -43,6 +43,9 @@ in the key-chain or PKCS#12 file containing the certificate. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md+3 -0
| @@ -42,6 +42,9 @@ currently does not work because of a bug in OpenSSL. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to internal default. |
| + | |
| # DEFAULT |
| |
| "PEM" |
docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md+4 -1
| @@ -45,7 +45,7 @@ separated by colons. |
| For setting TLS 1.3 ciphers see CURLOPT_TLS13_CIPHERS(3). |
| |
| A valid example of a cipher list is: |
| - | ~~~c |
| + | ~~~ |
| "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:" |
| "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305" |
| ~~~ |
| @@ -60,6 +60,9 @@ Find more details about cipher lists on this URL: |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, use built-in list |
docs/libcurl/opts/CURLOPT_SSL_EC_CURVES.md+10 -4
| @@ -25,14 +25,20 @@ CURLOPT_SSL_EC_CURVES - key exchange curves |
| ~~~c |
| #include <curl/curl.h> |
| |
| - | CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *alg_list); |
| + | CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_EC_CURVES, char *list); |
| ~~~ |
| |
| # 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 |
| - | the SSL backend libcurl is built to use supports it). |
| + | Pass a string as parameter with a colon delimited list of Elliptic curve (EC) |
| + | algorithms. This option defines the client's key exchange algorithms in the |
| + | SSL handshake (if the SSL backend libcurl is built to use supports it). |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore back to internal default. |
| |
| # DEFAULT |
| |
docs/libcurl/opts/CURLOPT_TELNETOPTIONS.md+6 -0
| @@ -32,6 +32,12 @@ negotiations. The variables should be in the format \<option=value\>. libcurl |
| supports the options **TTYPE**, **XDISPLOC** and **NEW_ENV**. See the TELNET |
| standard for details. |
| |
| + | Using this option multiple times makes the last set list override the previous |
| + | ones. Set it to NULL to disable its use again. |
| + | |
| + | libcurl does not copy the list, it needs to be kept around until after the |
| + | transfer has completed. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_TLS13_CIPHERS.md+3 -0
| @@ -55,6 +55,9 @@ Find more details about cipher lists on this URL: |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to internal default. |
| + | |
| # DEFAULT |
| |
| NULL, use internal built-in |
docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md+3 -0
| @@ -38,6 +38,9 @@ option also be set. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| This feature relies on TLS SRP which does not work with TLS 1.3. |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md+6 -0
| @@ -32,6 +32,12 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_TYPE, char *type); |
| Pass a pointer to a null-terminated string as parameter. The string should be |
| the method of the TLS authentication. Supported method is "SRP". |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to restore to internal default. |
| + | |
| + | The application does not have to keep the string around after setting this |
| + | option. |
| + | |
| ## SRP |
| |
| TLS-SRP authentication. Secure Remote Password authentication for TLS is |
docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md+3 -0
| @@ -37,6 +37,9 @@ option also be set. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| This feature relies on TLS SRP which does not work with TLS 1.3. |
| |
| # DEFAULT |
docs/libcurl/opts/CURLOPT_UNIX_SOCKET_PATH.md+7 -4
| @@ -38,14 +38,17 @@ does not resolve the DNS hostname in the URL. |
| The maximum path length on Cygwin, Linux and Solaris is 107. On other platforms |
| it might be even less. |
| |
| - | Proxy and TCP options such as CURLOPT_TCP_NODELAY(3) are not |
| - | supported. Proxy options such as 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 CURLOPT_TCP_NODELAY(3) are not supported. Proxy |
| + | options such as 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. |
| |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL - no Unix domain sockets are used. |
docs/libcurl/opts/CURLOPT_URL.md+4 -0
| @@ -71,6 +71,10 @@ transfer is started. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. Note however that |
| + | libcurl needs a URL set to be able to performed a transfer. |
| + | |
| The parser used for handling the URL set with CURLOPT_URL(3) is the same |
| that curl_url_set(3) uses. |
| |
docs/libcurl/opts/CURLOPT_USERAGENT.md+3 -0
| @@ -35,6 +35,9 @@ can also set any custom header with CURLOPT_HTTPHEADER(3). |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL, no User-Agent: header is used. |
docs/libcurl/opts/CURLOPT_USERPWD.md+3 -0
| @@ -63,6 +63,9 @@ for that, or include it in the URL. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |
docs/libcurl/opts/CURLOPT_XOAUTH2_BEARER.md+3 -0
| @@ -40,6 +40,9 @@ Token should be supplied via the CURLOPT_USERNAME(3) option. |
| The application does not have to keep the string around after setting this |
| option. |
| |
| + | Using this option multiple times makes the last set string override the |
| + | previous ones. Set it to NULL to disable its use again. |
| + | |
| # DEFAULT |
| |
| NULL |