aboutsummaryrefslogtreecommitdiff
path: root/docs/libcurl/opts
diff options
context:
space:
mode:
Diffstat (limited to 'docs/libcurl/opts')
-rw-r--r--docs/libcurl/opts/CURLOPT_COPYPOSTFIELDS.326
-rw-r--r--docs/libcurl/opts/CURLOPT_FOLLOWLOCATION.321
-rw-r--r--docs/libcurl/opts/CURLOPT_HTTPGET.315
-rw-r--r--docs/libcurl/opts/CURLOPT_HTTPPOST.324
-rw-r--r--docs/libcurl/opts/CURLOPT_MAXREDIRS.318
-rw-r--r--docs/libcurl/opts/CURLOPT_NOBODY.313
-rw-r--r--docs/libcurl/opts/CURLOPT_POSTFIELDS.317
-rw-r--r--docs/libcurl/opts/CURLOPT_POSTFIELDSIZE.316
-rw-r--r--docs/libcurl/opts/CURLOPT_POSTFIELDSIZE_LARGE.320
-rw-r--r--docs/libcurl/opts/CURLOPT_POSTREDIR.318
-rw-r--r--docs/libcurl/opts/CURLOPT_PROTOCOLS.347
-rw-r--r--docs/libcurl/opts/CURLOPT_REDIR_PROTOCOLS.345
-rw-r--r--docs/libcurl/opts/CURLOPT_URL.319
-rw-r--r--docs/libcurl/opts/CURLOPT_VERBOSE.319
14 files changed, 290 insertions, 28 deletions
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), "
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-02 04:19:45 +0000