diff options
Diffstat (limited to 'docs/libcurl')
25 files changed, 129 insertions, 164 deletions
diff --git a/docs/libcurl/gnurl_multi_socket_action.3 b/docs/libcurl/gnurl_multi_socket_action.3 index 99acbbaaf..35b709231 100644 --- a/docs/libcurl/gnurl_multi_socket_action.3 +++ b/docs/libcurl/gnurl_multi_socket_action.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -43,15 +43,14 @@ libcurl will test the descriptor internally. It is also permissible to pass CURL_SOCKET_TIMEOUT to the \fBsockfd\fP parameter in order to initiate the whole process or when a timeout occurs. -At return, \fBrunning_handles\fP points to the number -of running easy handles within the multi handle. When this number reaches -zero, all transfers are complete/done. When you call -\fIcurl_multi_socket_action(3)\fP on a specific socket and the counter -decreases by one, it DOES NOT necessarily mean that this exact socket/transfer -is the one that completed. Use \fIcurl_multi_info_read(3)\fP to figure out -which easy handle that completed. +At return, \fBrunning_handles\fP points to the number of running easy handles +within the multi handle. When this number reaches zero, all transfers are +complete/done. When you call \fIcurl_multi_socket_action(3)\fP on a specific +socket and the counter decreases by one, it DOES NOT necessarily mean that +this exact socket/transfer is the one that completed. Use +\fIcurl_multi_info_read(3)\fP to figure out which easy handle that completed. -The \fIcurl_multi_socket_action(3)\fP functions inform the application about +The \fIcurl_multi_socket_action(3)\fP function informs the application about updates in the socket (file descriptor) status by doing none, one, or multiple calls to the socket callback function set with the \fICURLMOPT_SOCKETFUNCTION(3)\fP option to \fIcurl_multi_setopt(3)\fP. They @@ -66,65 +65,6 @@ timeout action: call the \fIcurl_multi_socket_action(3)\fP function with the \fIcurl_multi_timeout(3)\fP function to poll the value at any given time, but for an event-based system using the callback is far better than relying on polling the timeout value. -.SH "CALLBACK DETAILS" - -The socket \fBcallback\fP function uses a prototype like this -.nf - - int curl_socket_callback(CURL *easy, /* easy handle */ - curl_socket_t s, /* socket */ - int action, /* see values below */ - void *userp, /* private callback pointer */ - void *socketp); /* private socket pointer, - \fBNULL\fP if not - previously assigned with - \fIcurl_multi_assign(3)\fP */ - -.fi -The callback MUST return 0. - -The \fIeasy\fP argument is a pointer to the easy handle that deals with this -particular socket. Note that a single handle may work with several sockets -simultaneously. - -The \fIs\fP argument is the actual socket value as you use it within your -system. - -The \fIaction\fP argument to the callback has one of five values: -.RS -.IP "CURL_POLL_NONE (0)" -register, not interested in readiness (yet) -.IP "CURL_POLL_IN (1)" -register, interested in read readiness -.IP "CURL_POLL_OUT (2)" -register, interested in write readiness -.IP "CURL_POLL_INOUT (3)" -register, interested in both read and write readiness -.IP "CURL_POLL_REMOVE (4)" -unregister -.RE - -The \fIsocketp\fP argument is a private pointer you have previously set with -\fIcurl_multi_assign(3)\fP to be associated with the \fIs\fP socket. If no -pointer has been set, socketp will be NULL. This argument is of course a -service to applications that want to keep certain data or structs that are -strictly associated to the given socket. - -The \fIuserp\fP argument is a private pointer you have previously set with -\fIcurl_multi_setopt(3)\fP and the \fICURLMOPT_SOCKETDATA(3)\fP option. -.SH "RETURN VALUE" -CURLMcode type, general libcurl multi interface error code. - -Before version 7.20.0: If you receive \fICURLM_CALL_MULTI_PERFORM\fP, this -basically means that you should call \fIcurl_multi_socket_action(3)\fP again -before you wait for more actions on libcurl's sockets. You don't have to do it -immediately, but the return code means that libcurl may have more data -available to return or that there may be more data to send off before it is -"satisfied". - -The return code from this function is for the whole multi stack. Problems -still might have occurred on individual transfers even when one of these -functions return OK. .SH "TYPICAL USAGE" 1. Create a multi handle diff --git a/docs/libcurl/gnurl_multi_wait.3 b/docs/libcurl/gnurl_multi_wait.3 index 286bebf68..d91481ab7 100644 --- a/docs/libcurl/gnurl_multi_wait.3 +++ b/docs/libcurl/gnurl_multi_wait.3 @@ -91,7 +91,7 @@ do { } if(mc != CURLM_OK) { - fprintf(stderr, "curl_multi failed, code %d.\n", mc); + fprintf(stderr, "curl_multi failed, code %d.\\n", mc); break; } diff --git a/docs/libcurl/libgnurl-security.3 b/docs/libcurl/libgnurl-security.3 index 0cfdddea8..da45ed7f6 100644 --- a/docs/libcurl/libgnurl-security.3 +++ b/docs/libcurl/libgnurl-security.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -97,8 +97,8 @@ Never ever switch off certificate verification. The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP redirects sent by a remote server. These redirects can refer to any kind of URL, not just HTTP. libcurl restricts the protocols allowed to be used in -redirects for security reasons: FILE, SCP, SMB and SMBS are disabled by -default. Applications are encouraged to restrict that set further. +redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are +enabled by default. Applications may opt to restrict that set further. A redirect to a file: URL would cause the libcurl to read (or write) arbitrary files from the local filesystem. If the application returns the data back to diff --git a/docs/libcurl/libgnurl-thread.3 b/docs/libcurl/libgnurl-thread.3 index ae1e387be..796a5bb59 100644 --- a/docs/libcurl/libgnurl-thread.3 +++ b/docs/libcurl/libgnurl-thread.3 @@ -41,14 +41,15 @@ then of course using the underlying SSL library multi-threaded and those libs might have their own requirements on this issue. You may need to provide one or two functions to allow it to function properly: .IP OpenSSL -OpenSSL 1.1.0 "can be safely used in multi-threaded applications provided that -support for the underlying OS threading API is built-in." +OpenSSL 1.1.0+ "can be safely used in multi-threaded applications provided that +support for the underlying OS threading API is built-in." In that case the +engine is used by libcurl in a way that is fully thread-safe. -https://www.openssl.org/docs/manmaster/crypto/threads.html#DESCRIPTION +https://www.openssl.org/docs/man1.1.0/man3/CRYPTO_THREAD_run_once.html#DESCRIPTION OpenSSL <= 1.0.2 the user must set callbacks. -https://www.openssl.org/docs/man1.0.2/crypto/threads.html#DESCRIPTION +https://www.openssl.org/docs/man1.0.2/man3/CRYPTO_set_locking_callback.html#DESCRIPTION https://curl.haxx.se/libcurl/c/opensslthreadlock.html diff --git a/docs/libcurl/libgnurl-tutorial.3 b/docs/libcurl/libgnurl-tutorial.3 index aeca76e2e..c06e37760 100644 --- a/docs/libcurl/libgnurl-tutorial.3 +++ b/docs/libcurl/libgnurl-tutorial.3 @@ -496,13 +496,13 @@ and then a file with binary contents and uploads the whole thing. .nf curl_mime *multipart = curl_mime_init(easyhandle); - curl_mimepart *part = curl_mime_addpart(mutipart); + curl_mimepart *part = curl_mime_addpart(multipart); curl_mime_name(part, "name"); curl_mime_data(part, "daniel", CURL_ZERO_TERMINATED); - part = curl_mime_addpart(mutipart); + part = curl_mime_addpart(multipart); curl_mime_name(part, "project"); curl_mime_data(part, "curl", CURL_ZERO_TERMINATED); - part = curl_mime_addpart(mutipart); + part = curl_mime_addpart(multipart); curl_mime_name(part, "logotype-image"); curl_mime_filedata(part, "curl.png"); diff --git a/docs/libcurl/opts/GNURLINFO_TLS_SSL_PTR.3 b/docs/libcurl/opts/GNURLINFO_TLS_SSL_PTR.3 index c8c99ab85..0f06b9af6 100644 --- a/docs/libcurl/opts/GNURLINFO_TLS_SSL_PTR.3 +++ b/docs/libcurl/opts/GNURLINFO_TLS_SSL_PTR.3 @@ -54,7 +54,7 @@ struct curl_tlssessioninfo { The \fIbackend\fP struct member is one of the defines in the CURLSSLBACKEND_* series: CURLSSLBACKEND_NONE (when built without TLS support), -CURLSSLBACKEND_CYASSL, CURLSSLBACKEND_DARWINSSL, +CURLSSLBACKEND_WOLFSSL, CURLSSLBACKEND_DARWINSSL, CURLSSLBACKEND_GNUTLS, CURLSSLBACKEND_GSKIT, CURLSSLBACKEND_MBEDTLS, CURLSSLBACKEND_NSS, CURLSSLBACKEND_OPENSSL, CURLSSLBACKEND_POLARSSL, CURLSSLBACKEND_SCHANNEL or CURLSSLBACKEND_MESALINK. (Note that the OpenSSL @@ -83,9 +83,9 @@ mbedtls_ssl_context * ssl_context * .IP "Secure Channel" CtxtHandle * -.IP "Secure Transport (DarwinSSL)" +.IP "Secure Transport" SSLContext * -.IP "WolfSSL (formerly CyaSSL)" +.IP "wolfSSL" SSL * .IP "MesaLink" SSL * @@ -95,26 +95,26 @@ If the \fIinternals\fP pointer is NULL then either the SSL backend is not supported, an SSL session has not yet been established or the connection is no longer associated with the easy handle (eg curl_easy_perform has returned). .SH LIMITATIONS -\fBThis option has some limitations that could make it unsafe when it comes to -the manual verification of certificates.\fP +This option has some limitations that could make it unsafe when it comes to +the manual verification of certificates. This option only retrieves the first in-use SSL session pointer for your easy handle, however your easy handle may have more than one in-use SSL session if using FTP over SSL. That is because the FTP protocol has a control channel and -a data channel and one or both may be over SSL. \fBCurrently there is no way to -retrieve a second in-use SSL session associated with an easy handle.\fP +a data channel and one or both may be over SSL. Currently there is no way to +retrieve a second in-use SSL session associated with an easy handle. -This option has not been thoroughly tested with plaintext protocols that can be -upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with +This option has not been thoroughly tested with plaintext protocols that can +be upgraded/downgraded to/from SSL: FTP, SMTP, POP3, IMAP when used with \fICURLOPT_USE_SSL(3)\fP. Though you will be able to retrieve the SSL pointer, -it's possible that before you can do that \fBdata (including auth) may have -already been sent over a connection after it was upgraded.\fP +it's possible that before you can do that data (including auth) may have +already been sent over a connection after it was upgraded. Renegotiation. If unsafe renegotiation or renegotiation in a way that the certificate is allowed to change is allowed by your SSL library this may occur -and the certificate may change, and \fBdata may continue to be sent or received +and the certificate may change, and data may continue to be sent or received after renegotiation but before you are able to get the (possibly) changed SSL -pointer,\fP with the (possibly) changed certificate information. +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 diff --git a/docs/libcurl/opts/GNURLMOPT_SOCKETFUNCTION.3 b/docs/libcurl/opts/GNURLMOPT_SOCKETFUNCTION.3 index 108f8eaa6..cd7b49dce 100644 --- a/docs/libcurl/opts/GNURLMOPT_SOCKETFUNCTION.3 +++ b/docs/libcurl/opts/GNURLMOPT_SOCKETFUNCTION.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -38,14 +38,24 @@ CURLMcode curl_multi_setopt(CURLM *handle, CURLMOPT_SOCKETFUNCTION, socket_callb Pass a pointer to your callback function, which should match the prototype shown above. -When the \fIcurl_multi_socket_action(3)\fP function runs, it informs the +When the \fIcurl_multi_socket_action(3)\fP function is called, it informs the application about updates in the socket (file descriptor) status by doing -none, one, or multiple calls to the \fBsocket_callback\fP. The callback gets -status updates with changes since the previous time the callback was called. -If the given callback pointer is NULL, no callback will be called. Set the -callback's \fBuserp\fP argument with \fICURLMOPT_SOCKETDATA(3)\fP. See -\fIcurl_multi_socket_action(3)\fP for more details on how the callback is used -and should work. +none, one, or multiple calls to the \fBsocket_callback\fP. The callback +function gets status updates with changes since the previous time the callback +was called. If the given callback pointer is set to NULL, no callback will be +called. +.SH "CALLBACK ARGUMENTS" +\fIeasy\fP identifies the specific transfer for which this update is related. + +\fIs\fP is the specific socket this function invocation concerns. If the +\fBwhat\fP argument is not CURL_POLL_REMOVE then it holds information about +what activity on this socket the application is supposed to +monitor. Subsequent calls to this callback might update the \fBwhat\fP bits +for a socket that is already monitored. + +\fBuserp\fP is set with \fICURLMOPT_SOCKETDATA(3)\fP. + +\fBsocketp\fP is set with \fIcurl_multi_assign(3)\fP or will be NULL. The \fBwhat\fP parameter informs the callback on the status of the given socket. It can hold one of these values: diff --git a/docs/libcurl/opts/GNURLOPT_CAINFO.3 b/docs/libcurl/opts/GNURLOPT_CAINFO.3 index 175660ef6..1a3ca4319 100644 --- a/docs/libcurl/opts/GNURLOPT_CAINFO.3 +++ b/docs/libcurl/opts/GNURLOPT_CAINFO.3 @@ -46,22 +46,20 @@ libnssckbi.so, which contains a more comprehensive set of trust information than supported by nss-pem, because libnssckbi.so also includes information about distrusted certificates. -(iOS and macOS) If curl is built against Secure Transport, then this -option is supported for backward compatibility with other SSL engines, but it -should not be set. If the option is not set, then curl will use the -certificates in the system and user Keychain to verify the peer, which is the -preferred method of verifying the peer's certificate chain. +(iOS and macOS) When curl uses Secure Transport this option is supported. If +the option is not set, then curl will use the certificates in the system and +user Keychain to verify the peer. (Schannel) This option is supported for Schannel in Windows 7 or later but we recommend not using it until Windows 8 since it works better starting then. -Added in libcurl 7.60. This option is supported for backward compatibility -with other SSL engines; instead it is recommended to use Windows' store of -root certificates (the default for Schannel). +If the option is not set, then curl will use the certificates in the Windows' +store of root certificates (the default for Schannel). The application does not have to keep the string around after setting this option. .SH DEFAULT -Built-in system specific +Built-in system specific. When curl is built with Secure Transport or +Schannel, this option is not set by default. .SH PROTOCOLS All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. .SH EXAMPLE @@ -75,8 +73,8 @@ if(curl) { } .fi .SH AVAILABILITY -For SSL engines that don't support certificate files the CURLOPT_CAINFO option -is ignored. Refer to https://curl.haxx.se/docs/ssl-compared.html +For the SSL engines that don't 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. diff --git a/docs/libcurl/opts/GNURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/GNURLOPT_FOLLOWLOCATION.3 index bacba572a..2b6372bd3 100644 --- a/docs/libcurl/opts/GNURLOPT_FOLLOWLOCATION.3 +++ b/docs/libcurl/opts/GNURLOPT_FOLLOWLOCATION.3 @@ -39,7 +39,8 @@ libcurl will follow. libcurl limits what protocols it automatically follows to. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP. By default libcurl -will allow all protocols on redirect except those disabled for security +will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). Older versions of +libcurl allowed all protocols on redirect except those disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 SMB and SMBS are also disabled. diff --git a/docs/libcurl/opts/GNURLOPT_HEADEROPT.3 b/docs/libcurl/opts/GNURLOPT_HEADEROPT.3 index 643f92ed5..eaea05dff 100644 --- a/docs/libcurl/opts/GNURLOPT_HEADEROPT.3 +++ b/docs/libcurl/opts/GNURLOPT_HEADEROPT.3 @@ -57,12 +57,14 @@ if(curl) { list = curl_slist_append(list, "Accept:"); curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); curl_easy_setopt(curl, CURLOPT_PROXY, "http://localhost:8080"); + curl_easy_setopt(curl, CURLOPT_HTTPHEADER, list); /* HTTPS over a proxy makes a separate CONNECT to the proxy, so tell libcurl to not send the custom headers to the proxy. Keep them separate! */ curl_easy_setopt(curl, CURLOPT_HEADEROPT, CURLHEADER_SEPARATE); ret = curl_easy_perform(curl); + curl_slist_free_all(list); curl_easy_cleanup(curl); } .fi diff --git a/docs/libcurl/opts/GNURLOPT_HTTP_VERSION.3 b/docs/libcurl/opts/GNURLOPT_HTTP_VERSION.3 index 3d3bc74cc..3716ff933 100644 --- a/docs/libcurl/opts/GNURLOPT_HTTP_VERSION.3 +++ b/docs/libcurl/opts/GNURLOPT_HTTP_VERSION.3 @@ -29,9 +29,7 @@ CURLOPT_HTTP_VERSION \- specify HTTP protocol version to use CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTP_VERSION, long version); .SH DESCRIPTION Pass \fIversion\fP a long, set to one of the values described below. They ask -libcurl to use the specific HTTP versions. This is not sensible to do unless -you have a good reason. You have to set this option if you want to use -libcurl's HTTP/2 support. +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 diff --git a/docs/libcurl/opts/GNURLOPT_MAIL_RCPT.3 b/docs/libcurl/opts/GNURLOPT_MAIL_RCPT.3 index 708c742a6..af43f235c 100644 --- a/docs/libcurl/opts/GNURLOPT_MAIL_RCPT.3 +++ b/docs/libcurl/opts/GNURLOPT_MAIL_RCPT.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -31,9 +31,10 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_MAIL_RCPT, struct curl_slist *rcpts); .SH DESCRIPTION Pass a pointer to a linked list of recipients to pass to the server in your -SMTP mail request. The linked list should be a fully valid list of \fBstruct -curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to -create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list. +SMTP mail request. The linked list should be a fully valid list of +\fBstruct curl_slist\fP structs properly filled in. Use +\fIcurl_slist_append(3)\fP to create the list and \fIcurl_slist_free_all(3)\fP +to clean up an entire list. 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 diff --git a/docs/libcurl/opts/GNURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/GNURLOPT_PINNEDPUBLICKEY.3 index a0e15a686..e056f4b13 100644 --- a/docs/libcurl/opts/GNURLOPT_PINNEDPUBLICKEY.3 +++ b/docs/libcurl/opts/GNURLOPT_PINNEDPUBLICKEY.3 @@ -109,7 +109,7 @@ PEM/DER support: sha256 support: - 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL + 7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL 7.47.0: mbedtls diff --git a/docs/libcurl/opts/GNURLOPT_PROXY_SSLVERSION.3 b/docs/libcurl/opts/GNURLOPT_PROXY_SSLVERSION.3 index fe2f945e8..e09364277 100644 --- a/docs/libcurl/opts/GNURLOPT_PROXY_SSLVERSION.3 +++ b/docs/libcurl/opts/GNURLOPT_PROXY_SSLVERSION.3 @@ -69,6 +69,11 @@ The flag defines maximum supported TLS version as TLSv1.2. The flag defines maximum supported TLS version as TLSv1.3. (Added in 7.54.0) .RE + +In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were +documented to allow \fIonly\fP the specified TLS version, but behavior was +inconsistent depending on the TLS library. + .SH DEFAULT CURL_SSLVERSION_DEFAULT .SH PROTOCOLS diff --git a/docs/libcurl/opts/GNURLOPT_PROXY_SSL_OPTIONS.3 b/docs/libcurl/opts/GNURLOPT_PROXY_SSL_OPTIONS.3 index a994619df..7478e52f3 100644 --- a/docs/libcurl/opts/GNURLOPT_PROXY_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/GNURLOPT_PROXY_SSL_OPTIONS.3 @@ -39,13 +39,10 @@ lessens the security, and by setting this option to 1 you ask for exactly that. This option is only supported for DarwinSSL, NSS and OpenSSL. \fICURLSSLOPT_NO_REVOKE\fP tells libcurl to disable certificate revocation -checks for those SSL backends where such behavior is present. \fBCurrently -this option is only supported for Schannel (the native Windows SSL library), -with an exception in the case of Windows' Untrusted Publishers blacklist which -it seems can't be bypassed.\fP This option may have broader support to -accommodate other SSL backends in the future. -https://curl.haxx.se/docs/ssl-compared.html - +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 blacklist which it +seems can't be bypassed. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/opts/GNURLOPT_RANGE.3 b/docs/libcurl/opts/GNURLOPT_RANGE.3 index dd393c27d..dcfbd58a8 100644 --- a/docs/libcurl/opts/GNURLOPT_RANGE.3 +++ b/docs/libcurl/opts/GNURLOPT_RANGE.3 @@ -43,6 +43,14 @@ For RTSP, the formatting of a range should follow RFC2326 Section 12.29. For RTSP, byte ranges are \fBnot\fP permitted. Instead, ranges should be given in npt, utc, or smpte formats. +For HTTP PUT uploads this option should not be used, since it may conflict with +other options. If you need to upload arbitrary parts of a file (like for +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 + Pass a NULL to this option to disable the use of ranges. The application does not have to keep the string around after setting this diff --git a/docs/libcurl/opts/GNURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/GNURLOPT_REDIR_PROTOCOLS.3 index cb5010f8f..3606b9379 100644 --- a/docs/libcurl/opts/GNURLOPT_REDIR_PROTOCOLS.3 +++ b/docs/libcurl/opts/GNURLOPT_REDIR_PROTOCOLS.3 @@ -37,10 +37,11 @@ redirections. Protocols denied by \fICURLOPT_PROTOCOLS(3)\fP are not overridden by this option. -By default libcurl will allow all protocols on redirect except several disabled -for security reasons: Since 7.19.4 FILE and SCP are disabled, and since 7.40.0 -SMB and SMBS are also disabled. \fICURLPROTO_ALL\fP enables all protocols on -redirect, including those disabled for security. +By default libcurl will allow HTTP, HTTPS, FTP and FTPS on redirect (7.65.2). +Older versions of libcurl allowed all protocols on redirect except several +disabled for security reasons: Since 7.19.4 FILE and SCP are disabled, and +since 7.40.0 SMB and SMBS are also disabled. \fICURLPROTO_ALL\fP enables all +protocols on redirect, including those disabled for security. These are the available protocol defines: .nf diff --git a/docs/libcurl/opts/GNURLOPT_RTSP_REQUEST.3 b/docs/libcurl/opts/GNURLOPT_RTSP_REQUEST.3 index f7d293c29..5bd47a309 100644 --- a/docs/libcurl/opts/GNURLOPT_RTSP_REQUEST.3 +++ b/docs/libcurl/opts/GNURLOPT_RTSP_REQUEST.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2014, 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -33,15 +33,15 @@ enum values as a long in the \fIrequest\fP argument. Unless noted otherwise, commands require the Session ID to be initialized. .IP CURL_RTSPREQ_OPTIONS Used to retrieve the available methods of the server. The application is -responsible for parsing and obeying the response. \fB(The session ID is not -needed for this method.)\fP +responsible for parsing and obeying the response. The session ID is not needed +for this method. .IP CURL_RTSPREQ_DESCRIBE Used to get the low level description of a stream. The application should note what formats it understands in the \fI'Accept:'\fP header. Unless set -manually, libcurl will automatically fill in \fI'Accept: -application/sdp'\fP. Time-condition headers will be added to Describe requests -if the \fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is -not needed for this method)\fP +manually, libcurl will automatically fill in \fI'Accept: application/sdp'\fP. +Time-condition headers will be added to Describe requests if the +\fICURLOPT_TIMECONDITION(3)\fP option is active. \fB(The session ID is not +needed for this method)\fP .IP CURL_RTSPREQ_ANNOUNCE When sent by a client, this method changes the description of the session. For example, if a client is using the server to record a meeting, the client can @@ -53,8 +53,8 @@ Setup is used to initialize the transport layer for the session. The application must set the desired Transport options for a session by using the \fICURLOPT_RTSP_TRANSPORT(3)\fP option prior to calling setup. If no session ID is currently set with \fICURLOPT_RTSP_SESSION_ID(3)\fP, libcurl will -extract and use the session ID in the response to this request. \fB(The -session ID is not needed for this method).\fP +extract and use the session ID in the response to this request. The session ID +is not needed for this method. .IP CURL_RTSPREQ_PLAY Send a Play command to the server. Use the \fICURLOPT_RANGE(3)\fP option to modify the playback time (e.g. 'npt=10-15'). diff --git a/docs/libcurl/opts/GNURLOPT_RTSP_STREAM_URI.3 b/docs/libcurl/opts/GNURLOPT_RTSP_STREAM_URI.3 index 3a8ac803f..9d9a00478 100644 --- a/docs/libcurl/opts/GNURLOPT_RTSP_STREAM_URI.3 +++ b/docs/libcurl/opts/GNURLOPT_RTSP_STREAM_URI.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -42,7 +42,7 @@ examples might be set to \fIrtsp://foo/twister\fP The application does not have to keep the string around after setting this option. .SH DEFAULT -'*' +\&'*' .SH PROTOCOLS RTSP .SH EXAMPLE diff --git a/docs/libcurl/opts/GNURLOPT_SEEKDATA.3 b/docs/libcurl/opts/GNURLOPT_SEEKDATA.3 index b898c7ce4..b864b78ad 100644 --- a/docs/libcurl/opts/GNURLOPT_SEEKDATA.3 +++ b/docs/libcurl/opts/GNURLOPT_SEEKDATA.3 @@ -40,7 +40,7 @@ HTTP, FTP, SFTP static int seek_cb(void *userp, curl_off_t offset, int origin) { struct data *d = (struct data *)userp; - lseek(our_fd, offset, origin); + lseek(d->our_fd, offset, origin); return CURL_SEEKFUNC_OK; } diff --git a/docs/libcurl/opts/GNURLOPT_SSLVERSION.3 b/docs/libcurl/opts/GNURLOPT_SSLVERSION.3 index 61c603610..8e1cc7f54 100644 --- a/docs/libcurl/opts/GNURLOPT_SSLVERSION.3 +++ b/docs/libcurl/opts/GNURLOPT_SSLVERSION.3 @@ -79,6 +79,11 @@ The flag defines maximum supported TLS version as TLS v1.2. The flag defines maximum supported TLS version as TLS v1.3. (Added in 7.54.0) .RE + +In versions of curl prior to 7.54 the CURL_SSLVERSION_TLS options were +documented to allow \fIonly\fP the specified TLS version, but behavior was +inconsistent depending on the TLS library. + .SH DEFAULT CURL_SSLVERSION_DEFAULT .SH PROTOCOLS diff --git a/docs/libcurl/opts/GNURLOPT_SSL_CTX_DATA.3 b/docs/libcurl/opts/GNURLOPT_SSL_CTX_DATA.3 index 7b4a7c702..166bb866e 100644 --- a/docs/libcurl/opts/GNURLOPT_SSL_CTX_DATA.3 +++ b/docs/libcurl/opts/GNURLOPT_SSL_CTX_DATA.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -112,8 +112,8 @@ int main(void) } .fi .SH AVAILABILITY -Added in 7.11.0 for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Other SSL -backends not supported. +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. .SH RETURN VALUE CURLE_OK if supported; or an error such as: diff --git a/docs/libcurl/opts/GNURLOPT_SSL_CTX_FUNCTION.3 b/docs/libcurl/opts/GNURLOPT_SSL_CTX_FUNCTION.3 index e75546ae0..49dd2ecf1 100644 --- a/docs/libcurl/opts/GNURLOPT_SSL_CTX_FUNCTION.3 +++ b/docs/libcurl/opts/GNURLOPT_SSL_CTX_FUNCTION.3 @@ -5,7 +5,7 @@ .\" * | (__| |_| | _ <| |___ .\" * \___|\___/|_| \_\_____| .\" * -.\" * Copyright (C) 1998 - 2018, Daniel Stenberg, <daniel@haxx.se>, et al. +.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <daniel@haxx.se>, et al. .\" * .\" * This software is licensed as described in the file COPYING, which .\" * you should have received as part of this distribution. The terms @@ -22,7 +22,7 @@ .\" .TH GNURLOPT_SSL_CTX_FUNCTION 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options" .SH NAME -CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL, wolfSSL/CyaSSL or mbedTLS +CURLOPT_SSL_CTX_FUNCTION \- SSL context callback for OpenSSL, wolfSSL or mbedTLS .SH SYNOPSIS .nf #include <gnurl/curl.h> @@ -32,9 +32,8 @@ CURLcode ssl_ctx_callback(CURL *curl, void *ssl_ctx, void *userptr); CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CTX_FUNCTION, ssl_ctx_callback); .SH DESCRIPTION -This option only works for libcurl powered by OpenSSL, wolfSSL/CyaSSL or -mbedTLS. If libcurl was built against another SSL library this functionality is -absent. +This option only works for libcurl powered by OpenSSL, wolfSSL or mbedTLS. If +libcurl was built against another SSL library this functionality is absent. Pass a pointer to your callback function, which should match the prototype shown above. @@ -43,11 +42,11 @@ This callback function gets called by libcurl just before the initialization of an SSL connection after having processed all other SSL related options to give a last chance to an application to modify the behavior of the SSL initialization. The \fIssl_ctx\fP parameter is actually a pointer to the SSL -library's \fISSL_CTX\fP for OpenSSL or wolfSSL/CyaSSL, and a pointer to -\fImbedtls_ssl_config\fP for mbedTLS. If an error is returned from the callback -no attempt to establish a connection is made and the perform operation will -return the callback's error code. Set the \fIuserptr\fP argument with the -\fICURLOPT_SSL_CTX_DATA(3)\fP option. +library's \fISSL_CTX\fP for OpenSSL or wolfSSL, and a pointer to +\fImbedtls_ssl_config\fP for mbedTLS. If an error is returned from the +callback no attempt to establish a connection is made and the perform +operation will return the callback's error code. Set the \fIuserptr\fP +argument with the \fICURLOPT_SSL_CTX_DATA(3)\fP option. This function will get called on all new connections made to a server, during the SSL negotiation. The \fIssl_ctx\fP will point to a newly initialized object @@ -72,8 +71,8 @@ See cacertinmem.c in docs/examples directory for usage example. https://curl.haxx.se/libcurl/c/cacertinmem.html .SH AVAILABILITY -Added in 7.11.0 for OpenSSL. Added in 7.42.0 for wolfSSL/CyaSSL. Added in -7.54.0 for mbedTLS. Other SSL backends not supported. +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. .SH RETURN VALUE CURLE_OK if supported; or an error such as: diff --git a/docs/libcurl/opts/GNURLOPT_SSL_OPTIONS.3 b/docs/libcurl/opts/GNURLOPT_SSL_OPTIONS.3 index 6964360cb..f3fc74ab3 100644 --- a/docs/libcurl/opts/GNURLOPT_SSL_OPTIONS.3 +++ b/docs/libcurl/opts/GNURLOPT_SSL_OPTIONS.3 @@ -41,12 +41,10 @@ This option is only supported for DarwinSSL, NSS and OpenSSL. Added in 7.44.0: \fICURLSSLOPT_NO_REVOKE\fP tells libcurl to disable certificate revocation -checks for those SSL backends where such behavior is present. \fBCurrently this -option is only supported for Schannel (the native Windows SSL library), with an -exception in the case of Windows' Untrusted Publishers blacklist which it seems -can't be bypassed.\fP This option may have broader support to accommodate other -SSL backends in the future. -https://curl.haxx.se/docs/ssl-compared.html +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 blacklist which it +seems can't be bypassed. .SH DEFAULT 0 .SH PROTOCOLS diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index 715badf97..5244a7cdb 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -345,6 +345,7 @@ CURLOPTTYPE_LONG 7.1 CURLOPTTYPE_OBJECTPOINT 7.1 CURLOPTTYPE_OFF_T 7.11.0 CURLOPTTYPE_STRINGPOINT 7.46.0 +CURLOPTTYPE_SLISTPOINT 7.65.2 CURLOPT_ABSTRACT_UNIX_SOCKET 7.53.0 CURLOPT_ACCEPTTIMEOUT_MS 7.24.0 CURLOPT_ACCEPT_ENCODING 7.21.6 |