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

14 files changed, 265 insertions, 37 deletions

diff --git a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3
index 843c4a942..06f841ee1 100644
--- a/docs/libcurl/opts/CURLINFO_HTTPAUTH_AVAIL.3
+++ b/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) {
diff --git a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3 b/docs/libcurl/opts/CURLINFO_OS_ERRNO.3
index b56d40ea2..6348d6cf8 100644
--- a/docs/libcurl/opts/CURLINFO_OS_ERRNO.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3 b/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3
index d07c5b953..2a7724080 100644
--- a/docs/libcurl/opts/CURLINFO_PROXYAUTH_AVAIL.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3
index 869b7f6cb..68e446d2a 100644
--- a/docs/libcurl/opts/CURLOPT_OPENSOCKETDATA.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3 b/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3
index 314e0c4ab..d57e24a3f 100644
--- a/docs/libcurl/opts/CURLOPT_OPENSOCKETFUNCTION.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3 b/docs/libcurl/opts/CURLOPT_PRE_PROXY.3
index c5f6dcf7f..8894c16da 100644
--- a/docs/libcurl/opts/CURLOPT_PRE_PROXY.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_PROXY.3 b/docs/libcurl/opts/CURLOPT_PROXY.3
index 65f84f528..3398170b0 100644
--- a/docs/libcurl/opts/CURLOPT_PROXY.3
+++ b/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.
diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3
index 00dd3166e..975c7eb96 100644
--- a/docs/libcurl/opts/CURLOPT_SOCKOPTDATA.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3 b/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3
index 6262dc591..c04d8aa33 100644
--- a/docs/libcurl/opts/CURLOPT_SOCKOPTFUNCTION.3
+++ b/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.
diff --git a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3 b/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
index 3073dadb4..150e02f12 100644
--- a/docs/libcurl/opts/CURLOPT_SSL_FALSESTART.3
+++ b/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.
diff --git a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3 b/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
index f8f934384..5949e3e44 100644
--- a/docs/libcurl/opts/CURLOPT_TCP_FASTOPEN.3
+++ b/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.
diff --git a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3 b/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3
index bd19fbaf0..701e31502 100644
--- a/docs/libcurl/opts/CURLOPT_TCP_NODELAY.3
+++ b/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
-algorithm is to try to minimize the number of small packets on the network
-(where "small packets" means TCP segments less than the Maximum Segment Size
-(MSS) for the network).
+Setting this option to 1L will disable TCP's Nagle algorithm on this
+connection. The purpose of this algorithm is to try to minimize the number of
+small packets on the network (where "small packets" means TCP segments less
+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
diff --git a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3 b/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3
index 242da13f0..9d5046e26 100644
--- a/docs/libcurl/opts/CURLOPT_TRANSFER_ENCODING.3
+++ b/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
diff --git a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3 b/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3
index 9e4cf269d..a0099b2ef 100644
--- a/docs/libcurl/opts/CURLOPT_UNRESTRICTED_AUTH.3
+++ b/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
-(user+password) credentials when following locations, even when hostname
-changed. This option is meaningful only when setting
+Set the long \fIgohead\fP parameter to 1L to make libcurl continue to send
+authentication (user+password) credentials when following locations, even when
+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