From c857bb68ec37f82b62238fca73942e6ede8bd8f7 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Tue, 21 Oct 2014 08:58:03 +0200 Subject: opts: added examples --- docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 | 26 ++++++++++---- docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 | 21 +++++++++-- docs/libcurl/opts/CURLOPT_HTTPGET.3 | 15 ++++++-- docs/libcurl/opts/CURLOPT_HTTPPOST.3 | 24 ++++++++++++- docs/libcurl/opts/CURLOPT_MAXREDIRS.3 | 18 ++++++++-- docs/libcurl/opts/CURLOPT_NOBODY.3 | 13 ++++++- docs/libcurl/opts/CURLOPT_POSTFIELDS.3 | 17 ++++++++- docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 | 16 ++++++++- docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 | 20 +++++++++-- docs/libcurl/opts/CURLOPT_POSTREDIR.3 | 18 ++++++++-- docs/libcurl/opts/CURLOPT_PROTOCOLS.3 | 47 +++++++++++++++++++++++-- docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 | 45 ++++++++++++++++++++++- docs/libcurl/opts/CURLOPT_URL.3 | 19 +++++++--- docs/libcurl/opts/CURLOPT_VERBOSE.3 | 19 +++++++++- 14 files changed, 290 insertions(+), 28 deletions(-) (limited to 'docs/libcurl') diff --git a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 index 35ae3ef01..d35aebd66 100644 --- a/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.3 @@ -28,10 +28,10 @@ CURLOPT_COPYPOSTFIELDS \- have libcurl copy data to POST CURLcode curl_easy_setopt(CURL *handle, CURLOPT_COPYPOSTFIELDS, char *data); .SH DESCRIPTION -Pass a char * as parameter, which should be the full data to post in a HTTP -POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but the -original data is instead copied by the library, allowing the application to -overwrite the original data after setting this option. +Pass a char * as parameter, which should be the full \fIdata\fP to post in a +HTTP POST operation. It behaves as the \fICURLOPT_POSTFIELDS(3)\fP option, but +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 \fICURLOPT_POSTFIELDSIZE(3)\fP or @@ -44,9 +44,23 @@ copy. In any case, the size must not be changed after .SH DEFAULT NULL .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + char local_buffer[1024]="data to send"; + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the data to copy from the buffer and send in the request */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* send data from the local stack */ + curl_easy_setopt(curl, CURLOPT_COPYPOSTFIELDS, local_buffer); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Added in 7.17.1 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 index 8885141b0..3a32caef5 100644 --- a/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 +++ b/docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.3 @@ -39,15 +39,32 @@ redirects libcurl will follow. libcurl can limit to what protocols it will automatically follow. The accepted protocols are set with \fICURLOPT_REDIR_PROTOCOLS(3)\fP and it excludes the FILE protocol by default. + +For users who think the existing location following is too naive, too simple +or just lacks features, it is very easy to instead implement your own redirect +follow logic with the use of \fIcurl_easy_getinfo(3)\fP's +\fICURLINFO_REDIRECT_URL\fP option instead of using +\fICURLOPT_FOLLOWLOCATION(3)\fP. .SH DEFAULT 0, disabled .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* example.com is redirected, so we tell libcurl to follow redirection */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Along with HTTP .SH RETURN VALUE Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_REDIR_PROTOCOLS "(3), " CURLOPT_PROTOCOLS "(3), " +.BR CURLOPT_POSTREDIR "(3), " diff --git a/docs/libcurl/opts/CURLOPT_HTTPGET.3 b/docs/libcurl/opts/CURLOPT_HTTPGET.3 index 1e3e5664a..c14c38784 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPGET.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPGET.3 @@ -37,9 +37,20 @@ When setting \fICURLOPT_HTTPGET(3)\fP to 1, it will automatically set .SH DEFAULT 0 .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* use a GET to fetch this */ + curl_easy_setopt(curl, CURLOPT_HTTPGET, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Along with HTTP .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 index b39e8f7e3..0f35b632a 100644 --- a/docs/libcurl/opts/CURLOPT_HTTPPOST.3 +++ b/docs/libcurl/opts/CURLOPT_HTTPPOST.3 @@ -47,7 +47,29 @@ NULL .SH PROTOCOLS HTTP .SH EXAMPLE -TODO +.nf +/* Fill in the file upload field. This makes libcurl load data from + the given file name when curl_easy_perform() is called. */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "sendfile", + CURLFORM_FILE, "postit2.c", + CURLFORM_END); + +/* Fill in the filename field */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "filename", + CURLFORM_COPYCONTENTS, "postit2.c", + CURLFORM_END); + +/* Fill in the submit field too, even if this is rarely needed */ +curl_formadd(&formpost, + &lastptr, + CURLFORM_COPYNAME, "submit", + CURLFORM_COPYCONTENTS, "send", + CURLFORM_END); +.fi .SH AVAILABILITY As long as HTTP is enabled .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 index 52d256767..34608c391 100644 --- a/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 +++ b/docs/libcurl/opts/CURLOPT_MAXREDIRS.3 @@ -39,9 +39,23 @@ Set it to -1 for an infinite number of redirects. .SH DEFAULT -1, unlimited .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/"); + + /* enable redirect following */ + curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L); + + /* allow three redirects */ + curl_easy_setopt(curl, CURLOPT_MAXREDIRS, 3L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Along with HTTP .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_NOBODY.3 b/docs/libcurl/opts/CURLOPT_NOBODY.3 index 0d7b7adcd..b303b95d9 100644 --- a/docs/libcurl/opts/CURLOPT_NOBODY.3 +++ b/docs/libcurl/opts/CURLOPT_NOBODY.3 @@ -39,7 +39,18 @@ Enabling this option means asking for a download but without a body. .SH PROTOCOLS Most .SH EXAMPLE -TODO +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* get us the resource without a body! */ + curl_easy_setopt(curl, CURLOPT_NOBODY, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Always .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 index b410bf6e8..d3a9ec3d1 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDS.3 @@ -58,7 +58,22 @@ NULL .SH PROTOCOLS HTTP .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, 12L); + + /* pass in a pointer to the data - libcurl will not copy */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Always .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 index 52be3f660..01668056e 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.3 @@ -39,7 +39,21 @@ If you post more than 2GB, use \fICURLOPT_POSTFIELDSIZE_LARGE(3)\fP. .SH PROTOCOLS HTTP .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = "data to send"; + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long) strlen(data)); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Along with HTTP .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 index 2bcb67e75..50fc3519c 100644 --- a/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 +++ b/docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.3 @@ -37,12 +37,28 @@ set to -1, the library will use strlen() to get the size. .SH DEFAULT -1 .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + const char *data = large_chunk; + curl_off_t length_of_data; /* set somehow */ + + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* size of the POST data */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE_LARGE, length_of_data); + + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, data); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Along with HTTP .SH RETURN VALUE Returns CURLE_OK if HTTP is supported, and CURLE_UNKNOWN_OPTION if not. .SH "SEE ALSO" .BR CURLOPT_POSTFIELDS "(3), " CURLOPT_COPYPOSTFIELDS "(3), " +.BR CURLOPT_POSTFIELDSIZE "(3), " diff --git a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 index b9660a944..aa36bd0f5 100644 --- a/docs/libcurl/opts/CURLOPT_POSTREDIR.3 +++ b/docs/libcurl/opts/CURLOPT_POSTREDIR.3 @@ -47,9 +47,23 @@ when setting \fICURLOPT_FOLLOWLOCATION(3)\fP. .SH DEFAULT 0 .SH PROTOCOLS -HTTP +HTTP(S) .SH EXAMPLE -TODO +.nf +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* a silly POST example */ + curl_easy_setopt(curl, CURLOPT_POSTFIELDS, "data=true"); + + /* example.com is redirected, so we tell libcurl to send POST on 301, 302 and + 303 HTTP response codes */ + curl_easy_setopt(curl, CURLOPT_POSTREDIR, CURL_REDIR_POST_ALL); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Added in 7.17.1. This option was known as CURLOPT_POST301 up to 7.19.0 as it only supported the 301 then. CURL_REDIR_POST_303 was added in 7.26.0. diff --git a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 index fafc46265..f3c63a9f6 100644 --- a/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_PROTOCOLS.3 @@ -32,14 +32,57 @@ Pass a long that holds a bitmask of CURLPROTO_* defines. If used, this bitmask limits what protocols libcurl may use in the transfer. This allows you to have a libcurl built to support a wide range of protocols but still limit specific transfers to only be allowed to use a subset of them. By default libcurl will -accept all protocols it supports. See also +accept all protocols it supports (\fICURLPROTO_ALL\fP). See also \fICURLOPT_REDIR_PROTOCOLS(3)\fP. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi .SH DEFAULT All protocols built-in .SH PROTOCOLS All .SH EXAMPLE -TODO +.nf +curl = curl_easy_init(); +if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow HTTP, TFTP and SFTP */ + curl_easy_setopt(curl, CURLOPT_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_TFTP | CURLPROTO_SFTP); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Added in 7.19.4 .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 index 0eb39c5f3..b7cbcb296 100644 --- a/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 +++ b/docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.3 @@ -34,12 +34,55 @@ redirect when \fICURLOPT_FOLLOWLOCATION(3)\fP is enabled. This allows you to limit specific transfers to only be allowed to use a subset of protocols in redirections. By default libcurl will allow all protocols except for FILE and SCP. + +These are the available protocol defines: +.nf +CURLPROTO_DICT +CURLPROTO_FILE +CURLPROTO_FTP +CURLPROTO_FTPS +CURLPROTO_GOPHER +CURLPROTO_HTTP +CURLPROTO_HTTPS +CURLPROTO_IMAP +CURLPROTO_IMAPS +CURLPROTO_LDAP +CURLPROTO_LDAPS +CURLPROTO_POP3 +CURLPROTO_POP3S +CURLPROTO_RTMP +CURLPROTO_RTMPE +CURLPROTO_RTMPS +CURLPROTO_RTMPT +CURLPROTO_RTMPTE +CURLPROTO_RTMPTS +CURLPROTO_RTSP +CURLPROTO_SCP +CURLPROTO_SFTP +CURLPROTO_SMTP +CURLPROTO_SMTPS +CURLPROTO_TELNET +CURLPROTO_TFTP +.fi .SH DEFAULT All protocols except for FILE and SCP .SH PROTOCOLS All .SH EXAMPLE -TODO +.nf +curl = curl_easy_init(); +if(curl) { + /* pass in the URL from an external source */ + curl_easy_setopt(curl, CURLOPT_URL, argv[1]); + + /* only allow redirects to HTTP and HTTPS URLs */ + curl_easy_setopt(curl, CURLOPT_REDIR_PROTOCOLS, + CURLPROTO_HTTP | CURLPROTO_HTTPS); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY Added in 7.19.4, before then it would follow all protocols. .SH RETURN VALUE diff --git a/docs/libcurl/opts/CURLOPT_URL.3 b/docs/libcurl/opts/CURLOPT_URL.3 index 96f5659cc..16b7d523f 100644 --- a/docs/libcurl/opts/CURLOPT_URL.3 +++ b/docs/libcurl/opts/CURLOPT_URL.3 @@ -272,12 +272,23 @@ performed. All .SH EXAMPLE .nf - curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); +CURL *curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + curl_easy_perform(curl); +} +.fi .SH AVAILABILITY -POP3 and SMTP added in 7.31.0 +POP3 and SMTP were added in 7.31.0 .SH RETURN VALUE -Returns CURLE_OK on success or -CURLE_OUT_OF_MEMORY if there was insufficient heap space. +Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient +heap space. + +Note that \fIcurl_easy_setopt(3)\fP won't actually parse the given string so +given a bad URL, it will not be detected until \fIcurl_easy_perform(3)\fP or +similar is called. .SH "SEE ALSO" .BR CURLOPT_VERBOSE "(3), " CURLOPT_PROTOCOLS "(3), " +.BR CURLOPT_FORBID_REUSE "(3), " CURLOPT_FRESH_CONNECT "(3), " .BR curl_easy_perform "(3)" diff --git a/docs/libcurl/opts/CURLOPT_VERBOSE.3 b/docs/libcurl/opts/CURLOPT_VERBOSE.3 index 53e29f9bc..4841a7b9f 100644 --- a/docs/libcurl/opts/CURLOPT_VERBOSE.3 +++ b/docs/libcurl/opts/CURLOPT_VERBOSE.3 @@ -40,7 +40,24 @@ To also get all the protocol data sent and received, consider using the \fICURLOPT_DEBUGFUNCTION(3)\fP. .SH DEFAULT 0, meaning disabled. +.SH PROTOCOLS +All +.SH EXAMPLE +.nf +curl = curl_easy_init(); +if(curl) { + curl_easy_setopt(curl, CURLOPT_URL, "http://example.com"); + + /* ask libcurl to show us the verbose output */ + curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L); + + /* Perform the request */ + curl_easy_perform(curl); +} +.fi +.SH AVAILABILITY +Always .SH RETURN VALUE -Returns CURLE_OK. +Returns CURLE_OK .SH "SEE ALSO" .BR CURLOPT_STDERR "(3), " CURLOPT_DEBUGFUNCTION "(3), " -- cgit v1.2.3