summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
authorDaniel Stenberg <daniel@haxx.se>2017-05-27 23:11:26 +0200
committerDaniel Stenberg <daniel@haxx.se>2017-05-27 23:11:26 +0200
commitc2227dae53e88fc0e39bb8c48bfad917e0c7b11e (patch)
treeb23d041b9e5361b1ce97b2fa1a4ad8d5761133d5 /docs
parent14514c97968c1ad26b15e140083565e85a4d2b47 (diff)
downloadcurl-c2227dae53e88fc0e39bb8c48bfad917e0c7b11e.tar.gz
opts: more examples added in option man pages
Diffstat (limited to 'docs')
-rw-r--r--docs/libcurl/opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_MAXCONNECTS.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_MAX_HOST_CONNECTIONS.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_MAX_PIPELINE_LENGTH.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.38
-rw-r--r--docs/libcurl/opts/CURLMOPT_PIPELINING.39
-rw-r--r--docs/libcurl/opts/CURLMOPT_PUSHDATA.334
-rw-r--r--docs/libcurl/opts/CURLMOPT_TIMERDATA.338
-rw-r--r--docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.351
-rw-r--r--docs/libcurl/opts/CURLOPT_CAINFO.312
-rw-r--r--docs/libcurl/opts/CURLOPT_CAPATH.312
-rw-r--r--docs/libcurl/opts/CURLOPT_CERTINFO.334
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