opts: added examples

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), "