moparisthebest
/
curl
mirror of https://github.com/moparisthebest/curl
1
0
Fork 0
Code Issues Releases Wiki Activity

docs/libcurl/opts: added more examples in man pages

This commit is contained in:
Daniel Stenberg 2017-05-15 11:45:19 +02:00
parent e366ca2b85
commit 5ddad099b4
14 changed files with 265 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3
View File

@ -43,7 +43,7 @@ if(curl) {
res = curl_easy_perform(curl);
if(!res) {
/* extract the content-type */
/* extract the available authentication types */
long auth;
res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth);
if(!res) {

19
docs/libcurl/opts/CURLINFO_OS_ERRNO.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -34,7 +34,22 @@ operation. The number is OS and system specific.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
CURLcode res;
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
res = curl_easy_perform(curl);
if(res != CURLE_OK) {
long error;
res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error);
if(res && error) {
printf("Errno: %ld\n", error);
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.12.2
.SH RETURN VALUE

30
docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -35,7 +35,33 @@ bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for
.SH PROTOCOLS
HTTP(S)
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80");
res = curl_easy_perform(curl);
if(!res) {
/* extract the available proxy authentication types */
long auth;
res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth);
if(!res) {
if(!auth)
printf("No proxy auth available, perhaps no 407?\\n");
else {
printf("%s%s%s%s\\n",
auth & CURLAUTH_BASIC ? "Basic ":"",
auth & CURLAUTH_DIGEST ? "Digest ":"",
auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"",
auth % CURLAUTH_NTLM ? "NTLM ":"");
}
}
}
curl_easy_cleanup(curl);
}
.fi
.SH AVAILABILITY
Added in 7.10.8
.SH RETURN VALUE

40
docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -35,7 +35,43 @@ The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH AVAILABILITY
Added in 7.17.1
.SH RETURN VALUE

39
docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -81,6 +81,43 @@ The default behavior is the equivalent of this:
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH AVAILABILITY
Added in 7.17.1.
.SH RETURN VALUE

12
docs/libcurl/opts/CURLOPT_PRE_PROXY.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -61,7 +61,15 @@ single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols don't do very well over proxy.
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_PREPROXY, "socks4://socks-proxy:1080");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.52.0
.SH RETURN VALUE

11
docs/libcurl/opts/CURLOPT_PROXY.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -85,7 +85,14 @@ single port number used widely for proxies. Specify it!
.SH PROTOCOLS
All except file://. Note that some protocols don't do very well over proxy.
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Since 7.14.1 the proxy environment variable names can include the protocol
scheme.

26
docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -35,7 +35,29 @@ The default value of this parameter is NULL.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
int val = *(int *)clientp;
setsockopt(curldfd, SOL_SOCKET, SO_RCVBUF, (const char *)&val, sizeof(val));
return CURL_SOCKOPT_OK;
}
curl = curl_easy_init();
if(curl) {
int recvbuffersize = 256 * 1024;
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH AVAILABILITY
Added in 7.16.0
.SH RETURN VALUE

40
docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -78,7 +78,43 @@ By default, this callback is NULL and unused.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
/* make libcurl use the already established socket 'sockfd' */
static curl_socket_t opensocket(void *clientp,
curlsocktype purpose,
struct curl_sockaddr *address)
{
curl_socket_t sockfd;
sockfd = *(curl_socket_t *)clientp;
/* the actual externally set socket is passed in via the OPENSOCKETDATA
option */
return sockfd;
}
static int sockopt_callback(void *clientp, curl_socket_t curlfd,
curlsocktype purpose)
{
/* This return code was added in libcurl 7.21.5 */
return CURL_SOCKOPT_ALREADY_CONNECTED;
}
curl = curl_easy_init();
if(curl) {
/* libcurl will internally think that you connect to the host
* and port that you specify in the URL option. */
curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
/* call this function to get a socket */
curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
/* call this function to set options for the socket */
curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
res = curl_easy_perform(curl);
curl_easy_cleanup(curl);
.fi
.SH AVAILABILITY
Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was
added in 7.21.5.

13
docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -28,7 +28,7 @@ CURLOPT_SSL_FALSESTART \- enable TLS false start
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable);
.SH DESCRIPTION
Pass a long as parameter set to 1 to enable or 0 to disable.
Pass a long as parameter set to 1L to enable or 0 to disable.
This option determines whether libcurl should use false start during the TLS
handshake. False start is a mode where a TLS client will start sending
@ -39,7 +39,14 @@ round trip when performing a full handshake.
.SH PROTOCOLS
All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
curl_easy_setopt(curl, CURLOPT_SSL_FALSESTART, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.42.0. This option is currently only supported by the NSS and
Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends.

13
docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -28,7 +28,7 @@ CURLOPT_TCP_FASTOPEN \- enable TCP Fast Open
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable);
.SH DESCRIPTION
Pass a long as parameter set to 1 to enable or 0 to disable.
Pass a long as parameter set to 1L to enable or 0 to disable.
TCP Fast Open (RFC7413) is a mechanism that allows data to be carried in the
SYN and SYN-ACK packets and consumed by the receiving end during the initial
@ -38,7 +38,14 @@ connection handshake, saving up to one full round-trip time (RTT).
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.49.0. This option is currently only supported on Linux and OS X
El Capitan.

22
docs/libcurl/opts/CURLOPT_TCP_NODELAY.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -29,13 +29,13 @@ CURLOPT_TCP_NODELAY \- set the TCP_NODELAY option
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay);
.SH DESCRIPTION
Pass a long specifying whether the TCP_NODELAY option is to be set or cleared
(1 = set, 0 = clear). The option is set by default. This will have no effect
(1L = set, 0 = clear). The option is set by default. This will have no effect
after the connection has been established.
Setting this option will disable TCP's Nagle algorithm. The purpose of this
algorithm is to try to minimize the number of small packets on the network
(where "small packets" means TCP segments less than the Maximum Segment Size
(MSS) for the network).
Setting this option to 1L will disable TCP's Nagle algorithm on this
connection. The purpose of this algorithm is to try to minimize the number of
small packets on the network (where "small packets" means TCP segments less
than the Maximum Segment Size (MSS) for the network).
Maximizing the amount of data sent per TCP segment is good because it
amortizes the overhead of the send. However, in some cases small segments may
@ -47,7 +47,15 @@ overdone.
.SH PROTOCOLS
All
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
/* disable Nagle */
curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 0);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Always. The default was changed to 1 from 0 in 7.50.2.
.SH RETURN VALUE

13
docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2016, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -28,7 +28,7 @@ CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, long enable);
.SH DESCRIPTION
Pass a long set to 1 to \fIenable\fP or 0 to disable.
Pass a long set to 1L to \fIenable\fP or 0 to disable.
Adds a request for compressed Transfer Encoding in the outgoing HTTP
request. If the server supports this and so desires, it can respond with the
@ -45,7 +45,14 @@ by both HTTP clients and HTTP servers.
.SH PROTOCOLS
HTTP
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Added in 7.21.6
.SH RETURN VALUE

22
docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3
View File

@ -5,7 +5,7 @@
.\" * | (__| |_| | _ <| |___
.\" * \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
@ -30,16 +30,28 @@ CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH,
long goahead);
.SH DESCRIPTION
A long parameter set to 1 tells libcurl it can continue to send authentication
(user+password) credentials when following locations, even when hostname
changed. This option is meaningful only when setting
Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send
authentication (user+password) credentials when following locations, even when
hostname changed. This option is meaningful only when setting
\fICURLOPT_FOLLOWLOCATION(3)\fP.
By default, libcurl will only send given credentials to the initial host name
as given in the original URL, to avoid leaking username + password to other
sites.
.SH DEFAULT
0
.SH PROTOCOLS
HTTP
.SH EXAMPLE
TODO
.nf
CURL *curl = curl_easy_init();
if(curl) {
curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L);
curl_easy_perform(curl);
}
.fi
.SH AVAILABILITY
Along with HTTP
.SH RETURN VALUE