From c2227dae53e88fc0e39bb8c48bfad917e0c7b11e Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Sat, 27 May 2017 23:11:26 +0200 Subject: [PATCH] opts: more examples added in option man pages --- .../opts/CURLMOPT_CHUNK_LENGTH_PENALTY_SIZE.3 | 8 ++- .../CURLMOPT_CONTENT_LENGTH_PENALTY_SIZE.3 | 8 ++- docs/libcurl/opts/CURLMOPT_MAXCONNECTS.3 | 8 ++- .../opts/CURLMOPT_MAX_HOST_CONNECTIONS.3 | 8 ++- .../opts/CURLMOPT_MAX_PIPELINE_LENGTH.3 | 8 ++- .../opts/CURLMOPT_MAX_TOTAL_CONNECTIONS.3 | 8 ++- docs/libcurl/opts/CURLMOPT_PIPELINING.3 | 9 +++- docs/libcurl/opts/CURLMOPT_PUSHDATA.3 | 34 ++++++++++++- docs/libcurl/opts/CURLMOPT_TIMERDATA.3 | 38 +++++++++++++- docs/libcurl/opts/CURLMOPT_TIMERFUNCTION.3 | 51 ++++++++++--------- docs/libcurl/opts/CURLOPT_CAINFO.3 | 12 ++++- docs/libcurl/opts/CURLOPT_CAPATH.3 | 12 ++++- docs/libcurl/opts/CURLOPT_CERTINFO.3 | 34 ++++++++++++- 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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, , et al. +.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, , 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