docs/libcurl/opts: added more examples in man pages

docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3

@@ -43,7 +43,7 @@ if(curl) {
   res = curl_easy_perform(curl);
 
   if(!res) {
-    /* extract the content-type */
+    /* extract the available authentication types */
     long auth;
     res = curl_easy_getinfo(curl, CURLINFO_HTTPAUTH_AVAIL, &auth);
     if(!res) {

docs/libcurl/opts/CURLINFO_OS_ERRNO.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
@@ -34,7 +34,22 @@ operation. The number is OS and system specific.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  CURLcode res;
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  res = curl_easy_perform(curl);
+  if(res != CURLE_OK) {
+    long error;
+    res = curl_easy_getinfo(curl, CURLINFO_OS_ERRNO, &error);
+    if(res && error) {
+      printf("Errno: %ld\n", error);
+    }
+  }
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.12.2
 .SH RETURN VALUE

docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.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
@@ -35,7 +35,33 @@ bits is explained in the \fICURLOPT_PROXYAUTH(3)\fP option for
 .SH PROTOCOLS
 HTTP(S)
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_setopt(curl, CURLOPT_PROXY, "http://127.0.0.1:80");
+
+  res = curl_easy_perform(curl);
+
+  if(!res) {
+    /* extract the available proxy authentication types */
+    long auth;
+    res = curl_easy_getinfo(curl, CURLINFO_PROXYAUTH_AVAIL, &auth);
+    if(!res) {
+      if(!auth)
+        printf("No proxy auth available, perhaps no 407?\\n");
+      else {
+        printf("%s%s%s%s\\n",
+               auth & CURLAUTH_BASIC ? "Basic ":"",
+               auth & CURLAUTH_DIGEST ? "Digest ":"",
+               auth & CURLAUTH_NEGOTIATE ? "Negotiate ":"",
+               auth % CURLAUTH_NTLM ? "NTLM ":"");
+      }
+    }
+  }
+  curl_easy_cleanup(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.10.8
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.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
@@ -35,7 +35,43 @@ The default value of this parameter is NULL.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+/* make libcurl use the already established socket 'sockfd' */
+
+static curl_socket_t opensocket(void *clientp,
+                                curlsocktype purpose,
+                                struct curl_sockaddr *address)
+{
+  curl_socket_t sockfd;
+  sockfd = *(curl_socket_t *)clientp;
+  /* the actual externally set socket is passed in via the OPENSOCKETDATA
+     option */
+  return sockfd;
+}
+
+static int sockopt_callback(void *clientp, curl_socket_t curlfd,
+                            curlsocktype purpose)
+{
+  /* This return code was added in libcurl 7.21.5 */
+  return CURL_SOCKOPT_ALREADY_CONNECTED;
+}
+
+curl = curl_easy_init();
+if(curl) {
+  /* libcurl will internally think that you connect to the host
+   * and port that you specify in the URL option. */
+  curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
+  /* call this function to get a socket */
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
+
+  /* call this function to set options for the socket */
+  curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
+
+  res = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+.fi
 .SH AVAILABILITY
 Added in 7.17.1
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.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
@@ -81,6 +81,43 @@ The default behavior is the equivalent of this:
 .SH PROTOCOLS
 All
 .SH EXAMPLE
+.nf
+/* make libcurl use the already established socket 'sockfd' */
+
+static curl_socket_t opensocket(void *clientp,
+                                curlsocktype purpose,
+                                struct curl_sockaddr *address)
+{
+  curl_socket_t sockfd;
+  sockfd = *(curl_socket_t *)clientp;
+  /* the actual externally set socket is passed in via the OPENSOCKETDATA
+     option */
+  return sockfd;
+}
+
+static int sockopt_callback(void *clientp, curl_socket_t curlfd,
+                            curlsocktype purpose)
+{
+  /* This return code was added in libcurl 7.21.5 */
+  return CURL_SOCKOPT_ALREADY_CONNECTED;
+}
+
+curl = curl_easy_init();
+if(curl) {
+  /* libcurl will internally think that you connect to the host
+   * and port that you specify in the URL option. */
+  curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
+  /* call this function to get a socket */
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
+
+  /* call this function to set options for the socket */
+  curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
+
+  res = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+.fi
 .SH AVAILABILITY
 Added in 7.17.1.
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_PRE_PROXY.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
@@ -61,7 +61,15 @@ single port number used widely for proxies. Specify it!
 .SH PROTOCOLS
 All except file://. Note that some protocols don't do very well over proxy.
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
+  curl_easy_setopt(curl, CURLOPT_PREPROXY, "socks4://socks-proxy:1080");
+  curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.52.0
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_PROXY.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
@@ -85,7 +85,14 @@ single port number used widely for proxies. Specify it!
 .SH PROTOCOLS
 All except file://. Note that some protocols don't do very well over proxy.
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/file.txt");
+  curl_easy_setopt(curl, CURLOPT_PROXY, "http://proxy:80");
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Since 7.14.1 the proxy environment variable names can include the protocol
 scheme.

docs/libcurl/opts/CURLOPT_SOCKOPTDATA.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
@@ -35,7 +35,29 @@ The default value of this parameter is NULL.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+static int sockopt_callback(void *clientp, curl_socket_t curlfd,
+                            curlsocktype purpose)
+{
+  int val = *(int *)clientp;
+  setsockopt(curldfd, SOL_SOCKET, SO_RCVBUF, (const char *)&val, sizeof(val));
+  return CURL_SOCKOPT_OK;
+}
+
+curl = curl_easy_init();
+if(curl) {
+  int recvbuffersize = 256 * 1024;
+
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
+
+  /* call this function to set options for the socket */
+  curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
+  curl_easy_setopt(curl, CURLOPT_SOCKOPTDATA, &recvbuffersize);
+
+  res = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+.fi
 .SH AVAILABILITY
 Added in 7.16.0
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.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
@@ -78,7 +78,43 @@ By default, this callback is NULL and unused.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+/* make libcurl use the already established socket 'sockfd' */
+
+static curl_socket_t opensocket(void *clientp,
+                                curlsocktype purpose,
+                                struct curl_sockaddr *address)
+{
+  curl_socket_t sockfd;
+  sockfd = *(curl_socket_t *)clientp;
+  /* the actual externally set socket is passed in via the OPENSOCKETDATA
+     option */
+  return sockfd;
+}
+
+static int sockopt_callback(void *clientp, curl_socket_t curlfd,
+                            curlsocktype purpose)
+{
+  /* This return code was added in libcurl 7.21.5 */
+  return CURL_SOCKOPT_ALREADY_CONNECTED;
+}
+
+curl = curl_easy_init();
+if(curl) {
+  /* libcurl will internally think that you connect to the host
+   * and port that you specify in the URL option. */
+  curl_easy_setopt(curl, CURLOPT_URL, "http://99.99.99.99:9999");
+  /* call this function to get a socket */
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETFUNCTION, opensocket);
+  curl_easy_setopt(curl, CURLOPT_OPENSOCKETDATA, &sockfd);
+
+  /* call this function to set options for the socket */
+  curl_easy_setopt(curl, CURLOPT_SOCKOPTFUNCTION, sockopt_callback);
+
+  res = curl_easy_perform(curl);
+
+  curl_easy_cleanup(curl);
+.fi
 .SH AVAILABILITY
 Added in 7.16.0. The \fICURL_SOCKOPT_ALREADY_CONNECTED\fP return code was
 added in 7.21.5.

docs/libcurl/opts/CURLOPT_SSL_FALSESTART.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
@@ -28,7 +28,7 @@ CURLOPT_SSL_FALSESTART \- enable TLS false start
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_FALSESTART, long enable);
 .SH DESCRIPTION
-Pass a long as parameter set to 1 to enable or 0 to disable.
+Pass a long as parameter set to 1L to enable or 0 to disable.
 
 This option determines whether libcurl should use false start during the TLS
 handshake. False start is a mode where a TLS client will start sending
@@ -39,7 +39,14 @@ round trip when performing a full handshake.
 .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_SSL_FALSESTART, 1L);
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.42.0. This option is currently only supported by the NSS and
 Secure Transport (on iOS 7.0 or later, or OS X 10.9 or later) TLS backends.

docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.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
@@ -28,7 +28,7 @@ CURLOPT_TCP_FASTOPEN \- enable TCP Fast Open
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_FASTOPEN, long enable);
 .SH DESCRIPTION
-Pass a long as parameter set to 1 to enable or 0 to disable.
+Pass a long as parameter set to 1L to enable or 0 to disable.
 
 TCP Fast Open (RFC7413) is a mechanism that allows data to be carried in the
 SYN and SYN-ACK packets and consumed by the receiving end during the initial
@@ -38,7 +38,14 @@ connection handshake, saving up to one full round-trip time (RTT).
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 1L);
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.49.0. This option is currently only supported on Linux and  OS X
 El Capitan.

docs/libcurl/opts/CURLOPT_TCP_NODELAY.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
@@ -29,13 +29,13 @@ CURLOPT_TCP_NODELAY \- set the TCP_NODELAY option
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TCP_NODELAY, long nodelay);
 .SH DESCRIPTION
 Pass a long specifying whether the TCP_NODELAY option is to be set or cleared
-(1 = set, 0 = clear). The option is set by default. This will have no effect
+(1L = set, 0 = clear). The option is set by default. This will have no effect
 after the connection has been established.
 
-Setting this option will disable TCP's Nagle algorithm. The purpose of this
+Setting this option to 1L will disable TCP's Nagle algorithm on this
-algorithm is to try to minimize the number of small packets on the network
+connection. The purpose of this algorithm is to try to minimize the number of
-(where "small packets" means TCP segments less than the Maximum Segment Size
+small packets on the network (where "small packets" means TCP segments less
-(MSS) for the network).
+than the Maximum Segment Size (MSS) for the network).
 
 Maximizing the amount of data sent per TCP segment is good because it
 amortizes the overhead of the send. However, in some cases small segments may
@@ -47,7 +47,15 @@ overdone.
 .SH PROTOCOLS
 All
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  /* disable Nagle */
+  curl_easy_setopt(curl, CURLOPT_TCP_FASTOPEN, 0);
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Always. The default was changed to 1 from 0 in 7.50.2.
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.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
@@ -28,7 +28,7 @@ CURLOPT_TRANSFER_ENCODING \- ask for HTTP Transfer Encoding
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TRANSFER_ENCODING, long enable);
 .SH DESCRIPTION
-Pass a long set to 1 to \fIenable\fP or 0 to disable.
+Pass a long set to 1L to \fIenable\fP or 0 to disable.
 
 Adds a request for compressed Transfer Encoding in the outgoing HTTP
 request. If the server supports this and so desires, it can respond with the
@@ -45,7 +45,14 @@ by both HTTP clients and HTTP servers.
 .SH PROTOCOLS
 HTTP
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_setopt(curl, CURLOPT_TRANSFER_ENCODING, 1L);
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Added in 7.21.6
 .SH RETURN VALUE

docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.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
@@ -30,16 +30,28 @@ CURLOPT_UNRESTRICTED_AUTH \- send credentials to other hosts too
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_UNRESTRICTED_AUTH,
                           long goahead);
 .SH DESCRIPTION
-A long parameter set to 1 tells libcurl it can continue to send authentication
+Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send
-(user+password) credentials when following locations, even when hostname
+authentication (user+password) credentials when following locations, even when
-changed. This option is meaningful only when setting
+hostname changed. This option is meaningful only when setting
 \fICURLOPT_FOLLOWLOCATION(3)\fP.
+
+By default, libcurl will only send given credentials to the initial host name
+as given in the original URL, to avoid leaking username + password to other
+sites.
 .SH DEFAULT
 0
 .SH PROTOCOLS
 HTTP
 .SH EXAMPLE
-TODO
+.nf
+CURL *curl = curl_easy_init();
+if(curl) {
+  curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
+  curl_easy_setopt(curl, CURLOPT_FOLLOWLOCATION, 1L);
+  curl_easy_setopt(curl, CURLOPT_UNRESTRICTED_AUTH, 1L);
+  curl_easy_perform(curl);
+}
+.fi
 .SH AVAILABILITY
 Along with HTTP
 .SH RETURN VALUE