opts: more examples added in option man pages
authorDaniel Stenberg <daniel@haxx.se>
Sat, 27 May 2017 21:11:26 +0000 (23:11 +0200)
committerDaniel Stenberg <daniel@haxx.se>
Sat, 27 May 2017 21:11:26 +0000 (23:11 +0200)
13 files changed:
docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3
docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3
docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3
docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.3
docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.3
docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3
docs/libcurl/opts/CURLMOPT_PIPELINING.3
docs/libcurl/opts/CURLMOPT_PUSHDATA.3
docs/libcurl/opts/CURLMOPT_TIMERDATA.3
docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3
docs/libcurl/opts/CURLOPT_CAINFO.3
docs/libcurl/opts/CURLOPT_CAPATH.3
docs/libcurl/opts/CURLOPT_CERTINFO.3

index ab2d2f63ecea3e182151d9b2205733f2fd73afc5..f0767608214cc7c61ce5392e29c50c18275db2b1 100644 (file)
@@ -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
index 3b4e81d677bdcfa4e78abcf86e773cc52e920893..c7a004041ba8fb381d3c0ee7cb6f6f12251619bc 100644 (file)
@@ -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
index ee9bdca7f940ef37c5127be43b7dc3f895c7a7ed..eda68568c7002bdc9addf74aa198d8c4761ef523 100644 (file)
@@ -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
index 2e0352f999047672a4b8c4ce7f80c725f455360a..9507a04ecea7be401144a70fdfaff66e8d03601e 100644 (file)
@@ -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
index 1204a0f9d509019acfb1d6173017454010a80181..4ced6bfb94f8b60995bededb95a0ff95f0a307b7 100644 (file)
@@ -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
index ea53bffffd1586df7ccc34ff6ae541ce539d02d6..bca000186c5025240924e2f8fcd46e9d3033091b 100644 (file)
@@ -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
index 1a4047659852ec7998f6a94cd69d3b034f50a909..796ac3c771ed90d216a8bc556e40b7feab94d8d3 100644 (file)
@@ -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
index ca9fe8a8837a1318c9280ede0ee857e408c374d0..d8ada0100763d5419b2e1601341a46ac021f2a28 100644 (file)
@@ -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
index 9d2b66f95b4f7e100b687782038cc8bfad0b85b2..6f590d3e77c4425b968db58726949d9d90f57e3e 100644 (file)
@@ -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
index 7fcb7a51a43dabcca0c5d753236ece7987b6e206..778a26c618bf5712cf825e8ae41c601db821ad93 100644 (file)
@@ -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);
index 43a4901f0f2527529375386f72f69706d3b8be93..bc094ef00c3965ab9eeb87aa1d0282eec8d2000a 100644 (file)
@@ -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
index b19994b503e797fcb274133117a09cd7ab198b07..32bd42d2a3d996740d091fa8856c1bac2a13e6fb 100644 (file)
@@ -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.
index e836e407d3a52094034995500a120df2ba385f6c..f60b1d54dcd7f37b556be3ac46e431a33273081a 100644 (file)
@@ -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