opts: more examples added in option man pages

13 files changed, 190 insertions, 48 deletions

diff --git a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
index ab2d2f63e..f07676082 100644
--- a/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
+++ b/docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
@@ -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
@@ -38,7 +38,11 @@ The default value is 0, which means that the penalization is inactive.
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+long maxchunk = 10000;
+curl_multi_setopt(m, CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE, maxchunk);
+.fi
 .SH AVAILABILITY
 Added in 7.30.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
index 3b4e81d67..c7a004041 100644
--- a/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
+++ b/docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
@@ -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
@@ -38,7 +38,11 @@ The default value is 0, which means that the size penalization is inactive.
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+long maxlength = 10000;
+curl_multi_setopt(m, CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE, maxlength);
+.fi
 .SH AVAILABILITY
 Added in 7.30.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
index ee9bdca7f..eda68568c 100644
--- a/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
+++ b/docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
@@ -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
@@ -51,7 +51,11 @@ See DESCRIPTION
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* only keep 10 connections in the cache */
+curl_multi_setopt(m, CURLMOPT_MAXCONNECTS, 10L);
+.fi
 .SH AVAILABILITY
 Added in 7.16.3
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
index 2e0352f99..9507a04ec 100644
--- a/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
+++ b/docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
@@ -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
@@ -49,7 +49,11 @@ considered to be the host for which this limit counts.
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* do no more than 2 connections per host */
+curl_multi_setopt(m, CURLMOPT_MAX_HOST_CONNECTIONS, 2L);
+.fi
 .SH AVAILABILITY
 Added in 7.30.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
index 1204a0f9d..4ced6bfb9 100644
--- a/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
+++ b/docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
@@ -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
@@ -42,7 +42,11 @@ total number of requests in-flight is \fICURLMOPT_MAX_HOST_CONNECTIONS(3)\fP *
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* set a more conservative pipe length */
+curl_multi_setopt(m, CURLMOPT_MAX_PIPELINE_LENGTH, 3L);
+.fi
 .SH AVAILABILITY
 Added in 7.30.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
index ea53bffff..bca000186 100644
--- a/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
+++ b/docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
@@ -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
@@ -41,7 +41,11 @@ controlled by the number of easy handles added.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* never do more than 15 connections */
+curl_multi_setopt(m, CURLMOPT_MAX_TOTAL_CONNECTIONS, 15L);
+.fi
 .SH AVAILABILITY
 Added in 7.30.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_PIPELINING.3 b/docs/libcurl/opts/CURLMOPT_PIPELINING.3
index 1a4047659..796ac3c77 100644
--- a/docs/libcurl/opts/CURLMOPT_PIPELINING.3
+++ b/docs/libcurl/opts/CURLMOPT_PIPELINING.3
@@ -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
@@ -65,7 +65,12 @@ existing connection if possible. This requires HTTP/2.
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURLM *m = curl_multi_init();
+/* try HTTP/1 pipelining and HTTP/2 multiplexing */
+curl_multi_setopt(m, CURLMOPT_PIPELINING, CURLPIPE_HTTP1 |
+                                          CURLPIPE_MULTIPLEX);
+.fi
 .SH AVAILABILITY
 Added in 7.16.0. Multiplex support bit added in 7.43.0.
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3 b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3
index ca9fe8a88..d8ada0100 100644
--- a/docs/libcurl/opts/CURLMOPT_PUSHDATA.3
+++ b/docs/libcurl/opts/CURLMOPT_PUSHDATA.3
@@ -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
@@ -38,7 +38,37 @@ NULL
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+/* only allow pushes for file names starting with "push-" */
+int push_callback(CURL *parent,
+                  CURL *easy,
+                  size_t num_headers,
+                  struct curl_pushheaders *headers,
+                  void *userp)
+{
+  char *headp;
+  int *transfers = (int *)userp;
+  FILE *out;
+  headp = curl_pushheader_byname(headers, ":path");
+  if(headp && !strncmp(headp, "/push-", 6)) {
+    fprintf(stderr, "The PATH is %s\\n", headp);
+
+    /* save the push here */
+    out = fopen("pushed-stream", "wb");
+
+    /* write to this file */
+    curl_easy_setopt(easy, CURLOPT_WRITEDATA, out);
+
+    (*transfers)++; /* one more */
+
+    return CURL_PUSH_OK;
+  }
+  return CURL_PUSH_DENY;
+}
+
+curl_multi_setopt(multi, CURLMOPT_PUSHFUNCTION, push_callback);
+curl_multi_setopt(multi, CURLMOPT_PUSHDATA, &counter);
+.fi
 .SH AVAILABILITY
 Added in 7.44.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3 b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
index 9d2b66f95..6f590d3e7 100644
--- a/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
+++ b/docs/libcurl/opts/CURLMOPT_TIMERDATA.3
@@ -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
@@ -39,7 +39,41 @@ NULL
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+static gboolean timeout_cb(gpointer user_data)
+{
+  int running;
+  if(user_data) {
+    g_free(user_data);
+    curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
+  }
+  curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
+  return G_SOURCE_REMOVE;
+}
+
+static int timerfunc(CURLM *multi, long timeout_ms, void *userp)
+{
+  guint *id = userp;
+
+  if(id)
+    g_source_remove(*id);
+
+  /* -1 means we should just delete our timer. */
+  if(timeout_ms == -1) {
+    g_free(id);
+    id = NULL;
+  }
+  else {
+    if(!id)
+      id = g_new(guint, 1);
+    *id = g_timeout_add(timeout_ms, timeout_cb, id);
+  }
+  curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);
+  return 0;
+}
+
+curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
+.fi
 .SH AVAILABILITY
 Added in 7.16.0
 .SH RETURN VALUE
diff --git a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
index 7fcb7a51a..778a26c61 100644
--- a/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
+++ b/docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
@@ -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
@@ -62,33 +62,36 @@ NULL
 All
 .SH EXAMPLE
 .nf
-static gboolean timeout_cb(gpointer user_data) {
-    if (user_data) {
-        g_free(user_data);
-        curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
-    }
-    int running;
-    curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
-    return G_SOURCE_REMOVE;
+static gboolean timeout_cb(gpointer user_data)
+{
+  int running;
+  if(user_data) {
+    g_free(user_data);
+    curl_multi_setopt(curl_handle, CURLMOPT_TIMERDATA, NULL);
+  }
+  curl_multi_socket_action(multi, CURL_SOCKET_TIMEOUT, 0, &running);
+  return G_SOURCE_REMOVE;
 }
 
-static int timerfunc(CURLM *multi, long timeout_ms, void *userp) {
-    guint *id = userp;
+static int timerfunc(CURLM *multi, long timeout_ms, void *userp)
+{
+  guint *id = userp;
 
-    if (id)
-        g_source_remove(*id);
+  if(id)
+    g_source_remove(*id);
 
-    // -1 means we should just delete our timer.
-    if (timeout_ms == -1) {
-        g_free(id);
-        id = NULL;
-    } else {
-        if (!id)
-            id = g_new(guint, 1);
-        *id = g_timeout_add(timeout_ms, timeout_cb, id);
-    }
-    curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);
-    return 0;
+  /* -1 means we should just delete our timer. */
+  if(timeout_ms == -1) {
+    g_free(id);
+    id = NULL;
+  }
+  else {
+    if(!id)
+      id = g_new(guint, 1);
+    *id = g_timeout_add(timeout_ms, timeout_cb, id);
+  }
+  curl_multi_setopt(multi, CURLMOPT_TIMERDATA, id);
+  return 0;
 }
 
 curl_multi_setopt(multi, CURLMOPT_TIMERFUNCTION, timerfunc);
diff --git a/docs/libcurl/opts/CURLOPT_CAINFO.3 b/docs/libcurl/opts/CURLOPT_CAINFO.3
index 43a4901f0..bc094ef00 100644
--- a/docs/libcurl/opts/CURLOPT_CAINFO.3
+++ b/docs/libcurl/opts/CURLOPT_CAINFO.3
@@ -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
@@ -59,7 +59,15 @@ Built-in system specific
 .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_CAINFO, "/etc/certs/cabundle.pem");
+  ret = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 For SSL engines that don't support certificate files the CURLOPT_CAINFO option
 is ignored. Refer to https://curl.haxx.se/docs/ssl-compared.html
diff --git a/docs/libcurl/opts/CURLOPT_CAPATH.3 b/docs/libcurl/opts/CURLOPT_CAPATH.3
index b19994b50..32bd42d2a 100644
--- a/docs/libcurl/opts/CURLOPT_CAPATH.3
+++ b/docs/libcurl/opts/CURLOPT_CAPATH.3
@@ -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
@@ -44,7 +44,15 @@ NULL
 .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_CAPATH, "/etc/cert-dir");
+  ret = curl_easy_perform(curl);
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 This option is supported by the OpenSSL, GnuTLS and PolarSSL backends. The NSS
 backend provides the option only for backward compatibility.
diff --git a/docs/libcurl/opts/CURLOPT_CERTINFO.3 b/docs/libcurl/opts/CURLOPT_CERTINFO.3
index e836e407d..f60b1d54d 100644
--- a/docs/libcurl/opts/CURLOPT_CERTINFO.3
+++ b/docs/libcurl/opts/CURLOPT_CERTINFO.3
@@ -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
@@ -38,7 +38,37 @@ its option \fICURLINFO_CERTINFO(3)\fP.
 .SH PROTOCOLS
 All TLS-based
 .SH EXAMPLE
-TODO
+.nf
+curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
+
+  /* connect to any HTTPS site, trusted or not */
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+  curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+
+  curl_easy_setopt(curl, CURLOPT_CERTINFO, 1L);
+
+  res = curl_easy_perform(curl);
+
+  if (!res) {
+    struct curl_certinfo *ci;
+    res = curl_easy_getinfo(curl, CURLINFO_CERTINFO, &ci);
+
+    if (!res) {
+      printf("%d certs!\\n", ci->num_of_certs);
+
+      for(i = 0; i < ci->num_of_certs; i++) {
+        struct curl_slist *slist;
+
+        for(slist = ci->certinfo[i]; slist; slist = slist->next)
+          printf("%s\\n", slist->data);
+      }
+    }
+  }
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 This option is supported by the OpenSSL, GnuTLS, NSS and GSKit backends.
 .SH RETURN VALUE