opts: added examples

2024-12-22 16:18:48 -05:00 · 2014-10-21 08:58:03 +02:00 · 2014-10-21 08:58:03 +02:00 · c857bb68ec
commit c857bb68ec
parent 005f2adaaa
14 changed files with 290 additions and 28 deletions
--- 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
--- 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), "
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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
--- 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), "
--- 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.
--- 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
--- 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
--- a/docs/libcurl/opts/CURLOPT_URL.3
+++ b/docs/libcurl/opts/CURLOPT_URL.3
@ -272,12 +272,23 @@ performed.
 All
 .SH EXAMPLE
 .nf
+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)"
--- 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), "