Merge branch 'master' into http2-pushhttp2-push

91 files changed, 1517 insertions, 1431 deletions

diff --git a/README b/README
index cfd676098..d92c7f8bf 100644
--- a/README
+++ b/README
@@ -38,7 +38,7 @@ GIT
 
   To download the very latest source off the GIT server do this:
 
-    git clone git://github.com/bagder/curl.git
+    git clone https://github.com/bagder/curl.git
 
   (you'll get a directory named curl created, filled with the source code)
 
diff --git a/RELEASE-NOTES b/RELEASE-NOTES
index 7db380b5a..e7fcc92eb 100644
--- a/RELEASE-NOTES
+++ b/RELEASE-NOTES
@@ -1,83 +1,19 @@
-Curl and libcurl 7.43.0
+Curl and libcurl 7.44.0
 
- Public curl releases:         147
+ Public curl releases:         148
  Command line options:         176
- curl_easy_setopt() options:   218
+ curl_easy_setopt() options:   219
  Public functions in libcurl:  58
- Contributors:                 1265
+ Contributors:                 1291
 
 This release includes the following changes:
 
- o Added CURLOPT_PROXY_SERVICE_NAME[11]
- o Added CURLOPT_SERVICE_NAME[12]
- o New curl option: --proxy-service-name[13]
- o Mew curl option: --service-name [14]
- o New curl option: --data-raw [5]
- o Added CURLOPT_PIPEWAIT [15]
- o Added support for multiplexing transfers using HTTP/2, enable this
-   with the new CURLPIPE_MULTIPLEX bit for CURLMOPT_PIPELINING [16]
- o HTTP/2: requires nghttp2 1.0.0 or later
- o scripts: add zsh.pl for generating zsh completion
- o curl.h: add CURL_HTTP_VERSION_2
+ o
+
 
 This release includes the following bugfixes:
 
- o nss: fix compilation failure with old versions of NSS [1]
- o curl_easy_getinfo.3: document 'internals' in CURLINFO_TLS_SESSION
- o schannel.c: Fix possible SEC_E_BUFFER_TOO_SMALL error
- o Curl_ossl_init: load builtin modules [2]
- o configure: follow-up fix for krb5-config [3]
- o sasl_sspi: Populate domain from the realm in the challenge [4]
- o netrc: support 'default' token
- o README: convert to UTF-8
- o cyassl: Implement public key pinning
- o nss: implement public key pinning for NSS backend
- o mingw build: add arch -m32/-m64 to LDFLAGS
- o schannel: Fix out of bounds array [6]
- o configure: remove autogenerated files by autoconf
- o configure: remove --automake from libtoolize call
- o acinclude.m4: fix shell test for default CA cert bundle/path
- o schannel: fix regression in schannel_recv [7]
- o openssl: skip trace outputs for ssl_ver == 0 [8]
- o gnutls: properly retrieve certificate status
- o netrc: Read in text mode when cygwin [9]
- o winbuild: Document the option used to statically link the CRT [10]
- o FTP: Make EPSV use the control IP address rather than the original host
- o FTP: fix dangling conn->ip_addr dereference on verbose EPSV
- o conncache: keep bundles on host+port bases, not only host names
- o runtests.pl: use 'h2c' now, no -14 anymore
- o curlver: introducing new version number (checking) macros
- o openssl: boringssl build brekage, use SSL_CTX_set_msg_callback [17]
- o CURLOPT_POSTFIELDS.3: correct variable names [18]
- o curl_easy_unescape.3: update RFC reference [19]
- o gnutls: don't fail on non-fatal alerts during handshake
- o testcurl.pl: allow source to be in an arbitrary directory
- o CURLOPT_HTTPPROXYTUNNEL.3: only works with a HTTP proxy
- o SSPI-error: Change SEC_E_ILLEGAL_MESSAGE description [20]
- o parse_proxy: switch off tunneling if non-HTTP proxy [21]
- o share_init: fix OOM crash
- o perl: remove subdir, not touched in 9 years
- o CURLOPT_COOKIELIST.3: Add example
- o CURLOPT_COOKIE.3: Explain that the cookies won't be modified [22]
- o CURLOPT_COOKIELIST.3: Explain Set-Cookie without a domain [23]
- o FAQ: How do I port libcurl to my OS?
- o openssl: Use TLS_client_method for OpenSSL 1.1.0+
- o HTTP-NTLM: fail auth on connection close instead of looping [24]
- o curl_setup: Add macros for FOPEN_READTEXT, FOPEN_WRITETEXT [25]
- o curl_getdate.3: update RFC reference
- o curl_multi_info_read.3: added example
- o curl_multi_perform.3: added example
- o curl_multi_timeout.3: added example
- o cookie: Stop exporting any-domain cookies [26]
- o openssl: remove dummy callback use from SSL_CTX_set_verify()
- o openssl: remove SSL_get_session()-using code
- o openssl: removed USERDATA_IN_PWD_CALLBACK kludge
- o openssl: removed error string #ifdef
- o openssl: Fix verification of server-sent legacy intermediates [27]
- o docs: man page indentation and syntax fixes
- o docs: Spelling fixes
- o fopen.c: fix a few compiler warnings
- o CURLOPT_OPENSOCKETFUNCTION: return error at once [28]
+ o
 
 This release includes the following known bugs:
 
@@ -86,45 +22,10 @@ This release includes the following known bugs:
 This release would not have looked like this without help, code, reports and
 advice from friends like these:
 
-  Alessandro Ghedini, Alexander Dyagilev, Anders Bakken, Anthony Avina,
-  Ashish Shukla, Bert Huijben, Brian Chrisman, Brian Prodoehl, Chris Araman,
-  Dagobert Michelsen, Dan Fandrich, Daniel Melani, Daniel Stenberg,
-  Dmitry Eremin-Solenikov, Egon Eckert, Fred Stluka, Gisle Vanem, Grant Pannell,
-  Isaac Boukris, Jens Rantil, Kamil Dudka, Linus Nielsen, Liviu Chircu,
-  Marc Hoersken, Michael Osipov, Oren Souroujon, Orgad Shaneh, Patrick Monnerat,
-  Patrick Rapin, Paul Howarth, Rafayel Mkrtchyan, Ray Satiro, Sean Boudreau,
-  Tatsuhiro Tsujikawa, Viktor Szakáts, Ville Skyttä, Yehezkel Horowitz,
-  (37 contributors)
+
 
         Thanks! (and sorry if I forgot to mention someone)
 
 References to bug reports and discussions on issues:
 
- [1] = http://curl.haxx.se/mail/lib-2015-04/0095.html
- [2] = https://github.com/bagder/curl/pull/206
- [3] = https://github.com/bagder/curl/commit/5b668606527613179d0349f21b4ab0df2971e3d2#commitcomment-10473445
- [4] = https://github.com/bagder/curl/pull/141
- [5] = https://github.com/bagder/curl/issues/198
- [6] = http://curl.haxx.se/mail/lib-2015-04/0199.html
- [7] = https://github.com/bagder/curl/issues/244
- [8] = https://github.com/bagder/curl/issues/219
- [9] = https://github.com/bagder/curl/pull/258
- [10] = https://github.com/bagder/curl/issues/254
- [11] = http://curl.haxx.se/libcurl/c/CURLOPT_PROXY_SERVICE_NAME.html
- [12] = http://curl.haxx.se/libcurl/c/CURLOPT_SERVICE_NAME.html
- [13] = http://curl.haxx.se/docs/manpage.html#--proxy-service-name
- [14] = http://curl.haxx.se/docs/manpage.html#--service-name
- [15] = http://curl.haxx.se/libcurl/c/CURLOPT_PIPEWAIT.html
- [16] = http://curl.haxx.se/libcurl/c/CURLMOPT_PIPELINING.html
- [17] = https://github.com/bagder/curl/issues/275
- [18] = https://github.com/bagder/curl/issues/281
- [19] = https://github.com/bagder/curl/issues/282
- [20] = https://github.com/bagder/curl/issues/267
- [21] = http://curl.haxx.se/mail/lib-2015-05/0056.html
- [22] = http://curl.haxx.se/mail/lib-2015-05/0115.html
- [23] = http://curl.haxx.se/mail/lib-2015-05/0137.html
- [24] = https://github.com/bagder/curl/issues/256
- [25] = https://github.com/bagder/curl/pull/258#issuecomment-107093055
- [26] = https://github.com/bagder/curl/issues/292
- [27] = https://rt.openssl.org/Ticket/Display.html?id=3621&user=guest&pass=guest
- [28] = http://curl.haxx.se/mail/lib-2015-06/0047.html
+ [1] =
diff --git a/docs/BINDINGS b/docs/BINDINGS
index c4722ebfc..fed16e990 100644
--- a/docs/BINDINGS
+++ b/docs/BINDINGS
@@ -78,7 +78,7 @@ Ferite
 
 Gambas
 
-  http://gambas.sourceforge.net
+  http://gambas.sourceforge.net/
 
 glib/GTK+
 
@@ -130,7 +130,7 @@ Mono
 .NET
 
   libcurl-net by Jeffrey Phillips
-  http://sourceforge.net/projects/libcurl-net/
+  https://sourceforge.net/projects/libcurl-net/
 
 node.js
 
@@ -145,7 +145,7 @@ Object-Pascal
 O'Caml
 
   Written by Lars Nilsson
-  http://sourceforge.net/projects/ocurl/
+  https://sourceforge.net/projects/ocurl/
 
 Pascal
 
@@ -160,7 +160,7 @@ Perl
 PHP
 
   Written by Sterling Hughes
-  http://php.net/curl
+  https://php.net/curl
 
 PostgreSQL
 
@@ -174,8 +174,7 @@ Python
 
 R
 
-  RCurl by Duncan Temple Lang
-  http://www.omegahat.org/RCurl/
+  http://cran.r-project.org/package=curl
 
 Rexx
 
@@ -234,7 +233,7 @@ Tcl
 Visual Basic
 
   libcurl-vb by Jeffrey Phillips
-  http://sourceforge.net/projects/libcurl-vb/
+  https://sourceforge.net/projects/libcurl-vb/
 
 Visual Foxpro
 
@@ -254,3 +253,8 @@ XBLite
 
   Written by David Szafranski
   http://perso.wanadoo.fr/xblite/libraries.html
+
+Xojo
+
+  Written by Andrew Lambert
+  https://github.com/charonn0/RB-libcURL
diff --git a/docs/CONTRIBUTE b/docs/CONTRIBUTE
index 47713838c..c6ea9773f 100644
--- a/docs/CONTRIBUTE
+++ b/docs/CONTRIBUTE
@@ -203,7 +203,7 @@
 
  You need to first checkout the repository:
 
-     git clone git://github.com/bagder/curl.git
+     git clone https://github.com/bagder/curl.git
 
  You then proceed and edit all the files you like and you commit them to your
  local repository:
@@ -245,8 +245,8 @@
 
  For unix-like operating systems:
 
-     http://www.gnu.org/software/patch/patch.html
-     http://www.gnu.org/directory/diffutils.html
+     https://savannah.gnu.org/projects/patch/
+     https://www.gnu.org/software/diffutils/
 
  For Windows:
 
diff --git a/docs/DISTRO-DILEMMA b/docs/DISTRO-DILEMMA
index 71186a268..2d317fdb0 100644
--- a/docs/DISTRO-DILEMMA
+++ b/docs/DISTRO-DILEMMA
@@ -112,7 +112,7 @@ The Better License, Original BSD, GPL or LGPL?
  In Debian land, there seems to be a common opinion that LGPL is "maximally
  compatible" with apps while Original BSD is not. Like this:
 
-        http://lists.debian.org/debian-devel/2005/09/msg01417.html
+        https://lists.debian.org/debian-devel/2005/09/msg01417.html
 
 More SSL Libraries
 
@@ -163,13 +163,13 @@ Distro Angle of this Problem
 Footnotes
 
  [1] = http://www.xfree86.org/3.3.6/COPYRIGHT2.html#6
- [2] = http://www.fsf.org/licensing/essays/bsd.html
- [3] = http://www.fsf.org/licensing/licenses/gpl.html
+ [2] = https://www.gnu.org/philosophy/bsd.html
+ [3] = https://www.gnu.org/licenses/gpl.html
  [4] = http://curl.haxx.se/docs/copyright.html
- [5] = http://www.openssl.org/source/license.html
- [6] = http://www.fsf.org/licensing/licenses/gpl.html end of section 3
- [7] = http://www.fsf.org/licensing/licenses/lgpl.html
- [8] = http://en.wikipedia.org/wiki/OpenSSL_exception
+ [5] = https://www.openssl.org/source/license.html
+ [6] = https://www.gnu.org/licenses/gpl.html end of section 3
+ [7] = https://www.gnu.org/licenses/lgpl.html
+ [8] = https://en.wikipedia.org/wiki/OpenSSL_exception
 
 Feedback/Updates provided by
 
diff --git a/docs/FAQ b/docs/FAQ
index 32e15302b..06a306d99 100644
--- a/docs/FAQ
+++ b/docs/FAQ
@@ -352,7 +352,7 @@ FAQ
   cryptography. When doing so, the Export Control Classification Number (ECCN)
   is used to identify the level of export control etc.
 
-  ASF gives a good explanation at http://www.apache.org/dev/crypto.html
+  ASF gives a good explanation at https://www.apache.org/dev/crypto.html
 
   We believe curl's number might be ECCN 5D002, another possibility is
   5D992. It seems necessary to write them, asking to confirm.
@@ -1042,7 +1042,7 @@ FAQ
   timeout is set.
 
   See option TcpMaxConnectRetransmissions on this page:
-  http://support.microsoft.com/?scid=kb%3Ben-us%3B175523&x=6&y=7
+  https://support.microsoft.com/en-us/kb/175523/en-us
 
   Also, even on non-Windows systems there may run a firewall or anti-virus
   software or similar that accepts the connection but does not actually do
@@ -1059,7 +1059,7 @@ FAQ
   You'll find that even if D:\blah.txt does exist, cURL returns a 'file
   not found' error.
 
-  According to RFC 1738 (http://www.faqs.org/rfcs/rfc1738.html),
+  According to RFC 1738 (https://www.ietf.org/rfc/rfc1738.txt),
   file:// URLs must contain a host component, but it is ignored by
   most implementations. In the above example, 'D:' is treated as the
   host component, and is taken away. Thus, cURL tries to open '/blah.txt'.
@@ -1163,13 +1163,13 @@ FAQ
   If you use a OpenSSL-powered libcurl in a multi-threaded environment, you
   need to provide one or two locking functions:
 
-    http://www.openssl.org/docs/crypto/threads.html
+    https://www.openssl.org/docs/crypto/threads.html
 
   If you use a GnuTLS-powered libcurl in a multi-threaded environment, you
   need to provide locking function(s) for libgcrypt (which is used by GnuTLS
   for the crypto functions).
 
-    http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html
+    https://web.archive.org/web/20111103083330/http://www.gnu.org/software/gnutls/manual/html_node/Multi_002dthreaded-applications.html
 
   No special locking is needed with a NSS-powered libcurl. NSS is thread-safe.
 
@@ -1345,7 +1345,7 @@ FAQ
   Also note that on many networks NATs or other IP-munging techniques are used
   that makes you see and use a different IP address locally than what the
   remote server will see you coming from. You may also consider using
-  http://www.torproject.org .
+  https://www.torproject.org/ .
 
   5.13 How do I stop an ongoing transfer?
 
diff --git a/docs/HTTP-COOKIES b/docs/HTTP-COOKIES
index 818e161ee..b5abddfa6 100644
--- a/docs/HTTP-COOKIES
+++ b/docs/HTTP-COOKIES
@@ -36,7 +36,7 @@ HTTP Cookies
   For a very long time, the only spec explaining how to use cookies was the
   original Netscape spec from 1994: http://curl.haxx.se/rfc/cookie_spec.html
 
-  In 2011, RFC6265 (http://www.ietf.org/rfc/rfc6265.txt) was finally published
+  In 2011, RFC6265 (https://www.ietf.org/rfc/rfc6265.txt) was finally published
   and details how cookies work within HTTP.
 
   1.2 Cookies saved to disk
diff --git a/docs/HTTP2.md b/docs/HTTP2.md
index ea14e57c5..b4e2983bd 100644
--- a/docs/HTTP2.md
+++ b/docs/HTTP2.md
@@ -1,7 +1,7 @@
 HTTP/2 with curl
 ================
 
-[HTTP/2 Spec](http://www.rfc-editor.org/rfc/rfc7540.txt)
+[HTTP/2 Spec](https://www.rfc-editor.org/rfc/rfc7540.txt)
 [http2 explained](http://daniel.haxx.se/http2/)
 
 Build prerequisites
@@ -95,7 +95,7 @@ same origin server that you get the response from. A browser or long-living
 client can use that hint to create a new connection asynchronously.  For
 libcurl, we may introduce a way to bring such clues to the applicaton and/or
 let a subsequent request use the alternate route
-automatically. [Spec](http://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05)
+automatically. [Spec](https://tools.ietf.org/html/draft-ietf-httpbis-alt-svc-05)
 
 TODO
 ----
diff --git a/docs/INSTALL b/docs/INSTALL
index 30dec5343..e7a929bf6 100644
--- a/docs/INSTALL
+++ b/docs/INSTALL
@@ -173,13 +173,13 @@ Win32
    advice given above.
 
    KB94248  - How To Use the C Run-Time
-              http://support.microsoft.com/kb/94248/en-us
+              https://support.microsoft.com/kb/94248/en-us
 
    KB140584 - How to link with the correct C Run-Time (CRT) library
-              http://support.microsoft.com/kb/140584/en-us
+              https://support.microsoft.com/kb/140584/en-us
 
    KB190799 - Potential Errors Passing CRT Objects Across DLL Boundaries
-              http://msdn.microsoft.com/en-us/library/ms235460
+              https://msdn.microsoft.com/en-us/library/ms235460
 
    If your app is misbehaving in some strange way, or it is suffering
    from memory corruption, before asking for further help, please try
@@ -209,8 +209,8 @@ Win32
    environment variables, for example:
 
      set ZLIB_PATH=c:\zlib-1.2.8
-     set OPENSSL_PATH=c:\openssl-0.9.8zc
-     set LIBSSH2_PATH=c:\libssh2-1.4.3
+     set OPENSSL_PATH=c:\openssl-1.0.2c
+     set LIBSSH2_PATH=c:\libssh2-1.6.0
 
    ATTENTION: if you want to build with libssh2 support you have to use latest
    version 0.17 - previous versions will NOT work with 7.17.0 and later!
@@ -232,7 +232,7 @@ Win32
    - optional MingW32-built OpenLDAP SDK available from:
      http://www.gknw.net/mirror/openldap/
    - optional recent Novell CLDAP SDK available from:
-     http://developer.novell.com/ndk/cldap.htm
+     https://www.novell.com/developer/ndk/ldap_libraries_for_c.html
 
    Cygwin
    ------
@@ -254,7 +254,7 @@ Win32
    If you use MSVC 6 it is required that you use the February 2003 edition of
    the 'Platform SDK' which can be downloaded from:
 
-   http://www.microsoft.com/en-us/download/details.aspx?id=12261
+   https://www.microsoft.com/en-us/download/details.aspx?id=12261
 
    Building any software with MSVC 6 without having PSDK installed is just
    asking for trouble down the road once you have released it, you might notice
@@ -263,7 +263,7 @@ Win32
    software built in such way will at some point regret having done so.
 
    If the compiler has been updated with the installation of a service pack as
-   those mentioned in http://support.microsoft.com/kb/194022 the compiler can be
+   those mentioned in https://support.microsoft.com/kb/194022 the compiler can be
    safely used to read source code, translate and make it object code.
 
    But, even with the service packs mentioned above installed, the resulting
@@ -299,7 +299,7 @@ Win32
    Then run 'nmake vc' in curl's root directory.
 
    If you want to compile with zlib support, you will need to build
-   zlib (http://www.gzip.org/zlib/) as well. Please read the zlib
+   zlib (http://www.zlib.net/) as well. Please read the zlib
    documentation on how to compile zlib. Define the ZLIB_PATH environment
    variable to the location of zlib.h and zlib.lib, for example:
 
@@ -471,6 +471,15 @@ Win32
    add '-DCURL_STATICLIB' to your CFLAGS.  Otherwise the linker will look for
    dynamic import symbols.
 
+   Legacy Windows and SSL
+   ----------------------
+   WinSSL (Windows SSPI, more specifically Schannel), is the native SSL library
+   that comes with the Windows OS. WinSSL in Windows <= XP is not able to
+   connect to servers that no longer support the legacy handshakes and
+   algorithms used by those versions. If you will be using curl in one of those
+   earlier versions of Windows you should choose another SSL backend like
+   OpenSSL.
+
 Apple iOS and Mac OS X
 ======================
 
@@ -665,12 +674,10 @@ NetWare
    - gnu make and awk running on the platform you compile on;
      native Win32 versions can be downloaded from:
      http://www.gknw.net/development/prgtools/
-   - recent Novell LibC SDK available from:
-     http://developer.novell.com/ndk/libc.htm
-   - or recent Novell CLib SDK available from:
-     http://developer.novell.com/ndk/clib.htm
+   - recent Novell LibC or Novell CLib SDK available from:
+     https://www.novell.com/developer/ndk/
    - optional recent Novell CLDAP SDK available from:
-     http://developer.novell.com/ndk/cldap.htm
+     https://www.novell.com/developer/ndk/ldap_libraries_for_c.html
    - optional zlib sources (static or dynamic linking with zlib.imp);
      sources with NetWare Makefile can be obtained from:
      http://www.gknw.net/mirror/zlib/
@@ -825,7 +832,7 @@ VxWorks
 
    To build libcurl for VxWorks you need:
 
-      - CYGWIN (free, http://cygwin.com/)
+      - CYGWIN (free, https://cygwin.com/)
       - Wind River Workbench (commercial)
 
    If you have CYGWIN and Workbench installed on you machine
@@ -1086,18 +1093,18 @@ Useful URLs
 
 axTLS        http://axtls.sourceforge.net/
 c-ares       http://c-ares.haxx.se/
-GNU GSS      http://www.gnu.org/software/gss/
-GnuTLS       http://www.gnu.org/software/gnutls/
-Heimdal      http://www.pdc.kth.se/heimdal/
-libidn       http://www.gnu.org/software/libidn/
+GNU GSS      https://www.gnu.org/software/gss/
+GnuTLS       https://www.gnu.org/software/gnutls/
+Heimdal      http://www.h5l.org/
+libidn       https://www.gnu.org/software/libidn/
 libmetalink  https://launchpad.net/libmetalink/
 libssh2      http://www.libssh2.org/
 MIT Kerberos http://web.mit.edu/kerberos/www/dist/
-NSS          http://www.mozilla.org/projects/security/pki/nss/
+NSS          https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS
 OpenLDAP     http://www.openldap.org/
-OpenSSL      http://www.openssl.org/
-PolarSSL     http://polarssl.org/
-yassl        http://www.yassl.com/
+OpenSSL      https://www.openssl.org/
+PolarSSL     https://tls.mbed.org/
+wolfSSL      https://www.wolfssl.com/wolfSSL/
 Zlib         http://www.zlib.net/
 
 MingW        http://www.mingw.org/
diff --git a/docs/INSTALL.devcpp b/docs/INSTALL.devcpp
index 46d1836af..ee2d7036f 100644
--- a/docs/INSTALL.devcpp
+++ b/docs/INSTALL.devcpp
@@ -95,7 +95,7 @@ install instructions may produce erratic behaviour in DevCpp. For further info
 check the following sites
 
 http://aditsu.freeunixhost.com/dev-cpp-faq.html
-http://sourceforge.net/forum/message.php?msg_id=3252213
+https://sourceforge.net/p/dev-cpp/discussion/48211/thread/2a85ea46
 
 As I have mentioned before I will confine this to the SSL Library compilations
 but the process is very similar for compilation of the executable - curl.exe;
diff --git a/docs/INTERNALS b/docs/INTERNALS
index fe5c44995..4cd63b4e2 100644
--- a/docs/INTERNALS
+++ b/docs/INTERNALS
@@ -1,18 +1,57 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
-INTERNALS
+Table of Contents
+=================
 
- The project is split in two. The library and the client. The client part uses
- the library, but the library is designed to allow other applications to use
- it.
+ - [Intro](#intro)
+ - [git](#git)
+ - [Portability](#Portability)
+ - [Windows vs Unix](#winvsunix)
+ - [Library](#Library)
+   - [`Curl_connect`](#Curl_connect)
+   - [`Curl_do`](#Curl_do)
+   - [`Curl_readwrite`](#Curl_readwrite)
+   - [`Curl_done`](#Curl_done)
+   - [`Curl_disconnect`](#Curl_disconnect)
+ - [HTTP(S)](#http)
+ - [FTP](#ftp)
+   - [Kerberos](#kerberos)
+ - [TELNET](#telnet)
+ - [FILE](#file)
+ - [SMB](#smb)
+ - [LDAP](#ldap)
+ - [E-mail](#email)
+ - [General](#general)
+ - [Persistent Connections](#persistent)
+ - [multi interface/non-blocking](#multi)
+ - [SSL libraries](#ssl)
+ - [Library Symbols](#symbols)
+ - [Return Codes and Informationals](#returncodes)
+ - [AP/ABI](#abi)
+ - [Client](#client)
+ - [Memory Debugging](#memorydebug)
+ - [Test Suite](#test)
+ - [Asynchronous name resolves](#asyncdns)
+   - [c-ares](#cares)
+ - [`curl_off_t`](#curl_off_t)
+ - [curlx](#curlx)
+ - [Content Encoding](#contentencoding)
+ - [hostip.c explained](#hostip)
+ - [Track Down Memory Leaks](#memoryleak)
+ - [`multi_socket`](#multi_socket)
+ - [Structs in libcurl](#structs)
+
+<a name="intro"></a>
+curl internals
+==============
+
+ This project is split in two. The library and the client. The client part
+ uses the library, but the library is designed to allow other applications to
+ use it.
 
  The largest amount of code and complexity is in the library part.
 
-GIT
+
+<a name="git"></a>
+git
 ===
 
  All changes to the sources are committed to the git repository as soon as
@@ -23,6 +62,7 @@ GIT
  Tagging shall be used extensively, and by the time we release new archives we
  should tag the sources with a name similar to the released version number.
 
+<a name="Portability"></a>
 Portability
 ===========
 
@@ -34,45 +74,55 @@ Portability
  want it to remain functional and buildable with these and later versions
  (older versions may still work but is not what we work hard to maintain):
 
- OpenSSL      0.9.7
- GnuTLS       1.2
- zlib         1.1.4
- libssh2      0.16
- c-ares       1.6.0
- libidn       0.4.1
- cyassl       2.0.0
- openldap     2.0
- MIT Kerberos 1.2.4
- GSKit        V5R3M0
- NSS          3.14.x
- axTLS        1.2.7
- PolarSSL     1.3.0
- Heimdal      ?
- nghttp2      1.0.0
+Dependencies
+------------
+
+ - OpenSSL      0.9.7
+ - GnuTLS       1.2
+ - zlib         1.1.4
+ - libssh2      0.16
+ - c-ares       1.6.0
+ - libidn       0.4.1
+ - cyassl       2.0.0
+ - openldap     2.0
+ - MIT Kerberos 1.2.4
+ - GSKit        V5R3M0
+ - NSS          3.14.x
+ - axTLS        1.2.7
+ - PolarSSL     1.3.0
+ - Heimdal      ?
+ - nghttp2      1.0.0
+
+Operating Systems
+-----------------
 
  On systems where configure runs, we aim at working on them all - if they have
  a suitable C compiler. On systems that don't run configure, we strive to keep
  curl running fine on:
 
- Windows      98
- AS/400       V5R3M0
- Symbian      9.1
- Windows CE   ?
- TPF          ?
+ - Windows      98
+ - AS/400       V5R3M0
+ - Symbian      9.1
+ - Windows CE   ?
+ - TPF          ?
+
+Build tools
+-----------
 
  When writing code (mostly for generating stuff included in release tarballs)
  we use a few "build tools" and we make sure that we remain functional with
  these versions:
 
- GNU Libtool  1.4.2
- GNU Autoconf 2.57
- GNU Automake 1.7 (we currently avoid 1.10 due to Solaris-related bugs)
- GNU M4       1.4
- perl         5.004
- roffit       0.5
- groff        ? (any version that supports "groff -Tps -man [in] [out]")
- ps2pdf (gs)  ?
+ - GNU Libtool  1.4.2
+ - GNU Autoconf 2.57
+ - GNU Automake 1.7
+ - GNU M4       1.4
+ - perl         5.004
+ - roffit       0.5
+ - groff        ? (any version that supports "groff -Tps -man [in] [out]")
+ - ps2pdf (gs)  ?
 
+<a name="winvsunix"></a>
 Windows vs Unix
 ===============
 
@@ -87,8 +137,9 @@ Windows vs Unix
 
  2. Windows requires a couple of init calls for the socket stuff.
 
-   That's taken care of by the curl_global_init() call, but if other libs also
-   do it etc there might be reasons for applications to alter that behaviour.
+   That's taken care of by the `curl_global_init()` call, but if other libs
+   also do it etc there might be reasons for applications to alter that
+   behaviour.
 
  3. The file descriptors for network communication and file operations are
     not easily interchangeable as in unix.
@@ -101,28 +152,29 @@ Windows vs Unix
 
    We set stdout to binary under windows
 
- Inside the source code, We make an effort to avoid '#ifdef [Your OS]'. All
+ Inside the source code, We make an effort to avoid `#ifdef [Your OS]`. All
  conditionals that deal with features *should* instead be in the format
- '#ifdef HAVE_THAT_WEIRD_FUNCTION'. Since Windows can't run configure scripts,
- we maintain a curl_config-win32.h file in lib directory that is supposed to
- look exactly as a curl_config.h file would have looked like on a Windows
+ `#ifdef HAVE_THAT_WEIRD_FUNCTION`. Since Windows can't run configure scripts,
+ we maintain a `curl_config-win32.h` file in lib directory that is supposed to
+ look exactly as a `curl_config.h` file would have looked like on a Windows
  machine!
 
  Generally speaking: always remember that this will be compiled on dozens of
  operating systems. Don't walk on the edge.
 
+<a name="Library"></a>
 Library
 =======
 
- (See LIBCURL-STRUCTS for a separate document describing all major internal
+ (See `LIBCURL-STRUCTS` for a separate document describing all major internal
  structs and their purposes.)
 
  There are plenty of entry points to the library, namely each publicly defined
  function that libcurl offers to applications. All of those functions are
- rather small and easy-to-follow. All the ones prefixed with 'curl_easy' are
+ rather small and easy-to-follow. All the ones prefixed with `curl_easy` are
  put in the lib/easy.c file.
 
- curl_global_init_() and curl_global_cleanup() should be called by the
+ `curl_global_init_()` and `curl_global_cleanup()` should be called by the
  application to initialize and clean up global stuff in the library. As of
  today, it can handle the global SSL initing if SSL is enabled and it can init
  the socket layer on windows machines. libcurl itself has no "global" scope.
@@ -130,51 +182,56 @@ Library
  All printf()-style functions use the supplied clones in lib/mprintf.c. This
  makes sure we stay absolutely platform independent.
 
- curl_easy_init() allocates an internal struct and makes some initializations.
- The returned handle does not reveal internals. This is the 'SessionHandle'
- struct which works as an "anchor" struct for all curl_easy functions. All
- connections performed will get connect-specific data allocated that should be
- used for things related to particular connections/requests.
+ [ `curl_easy_init()`][2] allocates an internal struct and makes some
+ initializations.  The returned handle does not reveal internals. This is the
+ 'SessionHandle' struct which works as an "anchor" struct for all `curl_easy`
+ functions. All connections performed will get connect-specific data allocated
+ that should be used for things related to particular connections/requests.
 
- curl_easy_setopt() takes three arguments, where the option stuff must be
- passed in pairs: the parameter-ID and the parameter-value. The list of
+ [`curl_easy_setopt()`][1] takes three arguments, where the option stuff must
+ be passed in pairs: the parameter-ID and the parameter-value. The list of
  options is documented in the man page. This function mainly sets things in
  the 'SessionHandle' struct.
 
- curl_easy_perform() is just a wrapper function that makes use of the multi
- API.  It basically curl_multi_init(), curl_multi_add_handle(),
- curl_multi_wait(), and curl_multi_perform() until the transfer is done and
- then returns.
+ `curl_easy_perform()` is just a wrapper function that makes use of the multi
+ API.  It basically calls `curl_multi_init()`, `curl_multi_add_handle()`,
+ `curl_multi_wait()`, and `curl_multi_perform()` until the transfer is done
+ and then returns.
 
  Some of the most important key functions in url.c are called from multi.c
  when certain key steps are to be made in the transfer operation.
 
- o Curl_connect()
+<a name="Curl_connect"></a>
+Curl_connect()
+--------------
 
    Analyzes the URL, it separates the different components and connects to the
    remote host. This may involve using a proxy and/or using SSL. The
-   Curl_resolv() function in lib/hostip.c is used for looking up host names
+   `Curl_resolv()` function in lib/hostip.c is used for looking up host names
    (it does then use the proper underlying method, which may vary between
    platforms and builds).
 
-   When Curl_connect is done, we are connected to the remote site. Then it is
-   time to tell the server to get a document/file. Curl_do() arranges this.
+   When `Curl_connect` is done, we are connected to the remote site. Then it
+   is time to tell the server to get a document/file. `Curl_do()` arranges
+   this.
 
    This function makes sure there's an allocated and initiated 'connectdata'
    struct that is used for this particular connection only (although there may
    be several requests performed on the same connect). A bunch of things are
    inited/inherited from the SessionHandle struct.
 
- o Curl_do()
+<a name="Curl_do"></a>
+Curl_do()
+---------
 
-   Curl_do() makes sure the proper protocol-specific function is called. The
+   `Curl_do()` makes sure the proper protocol-specific function is called. The
    functions are named after the protocols they handle.
 
    The protocol-specific functions of course deal with protocol-specific
-   negotiations and setup. They have access to the Curl_sendf() (from
+   negotiations and setup. They have access to the `Curl_sendf()` (from
    lib/sendf.c) function to send printf-style formatted data to the remote
    host and when they're ready to make the actual file transfer they call the
-   Curl_Transfer() function (in lib/transfer.c) to setup the transfer and
+   `Curl_Transfer()` function (in lib/transfer.c) to setup the transfer and
    returns.
 
    If this DO function fails and the connection is being re-used, libcurl will
@@ -183,11 +240,13 @@ Library
    we have discovered a dead connection before the DO function and thus we
    might wrongly be re-using a connection that was closed by the remote peer.
 
-   Some time during the DO function, the Curl_setup_transfer() function must
+   Some time during the DO function, the `Curl_setup_transfer()` function must
    be called with some basic info about the upcoming transfer: what socket(s)
    to read/write and the expected file transfer sizes (if known).
 
- o Curl_readwrite()
+<a name="Curl_readwrite"></a>
+Curl_readwrite()
+----------------
 
    Called during the transfer of the actual protocol payload.
 
@@ -196,18 +255,22 @@ Library
    called). The speedcheck functions in lib/speedcheck.c are also used to
    verify that the transfer is as fast as required.
 
- o Curl_done()
+<a name="Curl_done"></a>
+Curl_done()
+-----------
 
    Called after a transfer is done. This function takes care of everything
    that has to be done after a transfer. This function attempts to leave
-   matters in a state so that Curl_do() should be possible to call again on
+   matters in a state so that `Curl_do()` should be possible to call again on
    the same connection (in a persistent connection case). It might also soon
-   be closed with Curl_disconnect().
+   be closed with `Curl_disconnect()`.
 
- o Curl_disconnect()
+<a name="Curl_disconnect"></a>
+Curl_disconnect()
+-----------------
 
    When doing normal connections and transfers, no one ever tries to close any
-   connections so this is not normally called when curl_easy_perform() is
+   connections so this is not normally called when `curl_easy_perform()` is
    used. This function is only used when we are certain that no more transfers
    is going to be made on the connection. It can be also closed by force, or
    it can be called to make sure that libcurl doesn't keep too many
@@ -216,8 +279,9 @@ Library
    This function cleans up all resources that are associated with a single
    connection.
 
-
- HTTP(S)
+<a name="http"></a>
+HTTP(S)
+=======
 
  HTTP offers a lot and is the protocol in curl that uses the most lines of
  code. There is a special file (lib/formdata.c) that offers all the multipart
@@ -229,100 +293,123 @@ Library
  HTTPS uses in almost every means the same procedure as HTTP, with only two
  exceptions: the connect procedure is different and the function used to read
  or write from the socket is different, although the latter fact is hidden in
- the source by the use of Curl_read() for reading and Curl_write() for writing
- data to the remote server.
+ the source by the use of `Curl_read()` for reading and `Curl_write()` for
+ writing data to the remote server.
 
- http_chunks.c contains functions that understands HTTP 1.1 chunked transfer
+ `http_chunks.c` contains functions that understands HTTP 1.1 chunked transfer
  encoding.
 
- An interesting detail with the HTTP(S) request, is the Curl_add_buffer()
+ An interesting detail with the HTTP(S) request, is the `Curl_add_buffer()`
  series of functions we use. They append data to one single buffer, and when
  the building is done the entire request is sent off in one single write. This
  is done this way to overcome problems with flawed firewalls and lame servers.
 
- FTP
+<a name="ftp"></a>
+FTP
+===
 
- The Curl_if2ip() function can be used for getting the IP number of a
+ The `Curl_if2ip()` function can be used for getting the IP number of a
  specified network interface, and it resides in lib/if2ip.c.
 
- Curl_ftpsendf() is used for sending FTP commands to the remote server. It was
- made a separate function to prevent us programmers from forgetting that they
- must be CRLF terminated. They must also be sent in one single write() to make
- firewalls and similar happy.
+ `Curl_ftpsendf()` is used for sending FTP commands to the remote server. It
+ was made a separate function to prevent us programmers from forgetting that
+ they must be CRLF terminated. They must also be sent in one single write() to
+ make firewalls and similar happy.
 
- Kerberos
+<a name="kerberos"></a>
+Kerberos
+--------
 
  Kerberos support is mainly in lib/krb5.c and lib/security.c but also
- curl_sasl_sspi.c and curl_sasl_gssapi.c for the email protocols and
- socks_gssapi.c & socks_sspi.c for SOCKS5 proxy specifics.
+ `curl_sasl_sspi.c` and `curl_sasl_gssapi.c` for the email protocols and
+ `socks_gssapi.c` and `socks_sspi.c` for SOCKS5 proxy specifics.
 
- TELNET
+<a name="telnet"></a>
+TELNET
+======
 
  Telnet is implemented in lib/telnet.c.
 
- FILE
+<a name="file"></a>
+FILE
+====
 
  The file:// protocol is dealt with in lib/file.c.
 
- SMB
+<a name="smb"></a>
+SMB
+===
 
  The smb:// protocol is dealt with in lib/smb.c.
 
- LDAP
+<a name="ldap"></a>
+LDAP
+====
 
  Everything LDAP is in lib/ldap.c and lib/openldap.c
 
- E-mail
+<a name="email"></a>
+E-mail
+======
 
  The e-mail related source code is in lib/imap.c, lib/pop3.c and lib/smtp.c.
 
- GENERAL
+<a name="general"></a>
+General
+=======
 
  URL encoding and decoding, called escaping and unescaping in the source code,
  is found in lib/escape.c.
 
  While transferring data in Transfer() a few functions might get used.
- curl_getdate() in lib/parsedate.c is for HTTP date comparisons (and more).
+ `curl_getdate()` in lib/parsedate.c is for HTTP date comparisons (and more).
 
- lib/getenv.c offers curl_getenv() which is for reading environment variables
- in a neat platform independent way. That's used in the client, but also in
- lib/url.c when checking the proxy environment variables. Note that contrary
- to the normal unix getenv(), this returns an allocated buffer that must be
- free()ed after use.
+ lib/getenv.c offers `curl_getenv()` which is for reading environment
+ variables in a neat platform independent way. That's used in the client, but
+ also in lib/url.c when checking the proxy environment variables. Note that
+ contrary to the normal unix getenv(), this returns an allocated buffer that
+ must be free()ed after use.
 
  lib/netrc.c holds the .netrc parser
 
  lib/timeval.c features replacement functions for systems that don't have
  gettimeofday() and a few support functions for timeval conversions.
 
- A function named curl_version() that returns the full curl version string is
- found in lib/version.c.
+ A function named `curl_version()` that returns the full curl version string
+ is found in lib/version.c.
 
+<a name="persistent"></a>
 Persistent Connections
 ======================
 
  The persistent connection support in libcurl requires some considerations on
  how to do things inside of the library.
 
- o The 'SessionHandle' struct returned in the curl_easy_init() call must never
-   hold connection-oriented data. It is meant to hold the root data as well as
-   all the options etc that the library-user may choose.
- o The 'SessionHandle' struct holds the "connection cache" (an array of
+ - The 'SessionHandle' struct returned in the [`curl_easy_init()`][2] call
+   must never hold connection-oriented data. It is meant to hold the root data
+   as well as all the options etc that the library-user may choose.
+
+ - The 'SessionHandle' struct holds the "connection cache" (an array of
    pointers to 'connectdata' structs).
- o This enables the 'curl handle' to be reused on subsequent transfers.
- o When libcurl is told to perform a transfer, it first checks for an already
+
+ - This enables the 'curl handle' to be reused on subsequent transfers.
+
+ - When libcurl is told to perform a transfer, it first checks for an already
    existing connection in the cache that we can use. Otherwise it creates a
    new one and adds that the cache. If the cache is full already when a new
    connection is added added, it will first close the oldest unused one.
- o When the transfer operation is complete, the connection is left
+
+ - When the transfer operation is complete, the connection is left
    open. Particular options may tell libcurl not to, and protocols may signal
    closure on connections and then they won't be kept open of course.
- o When curl_easy_cleanup() is called, we close all still opened connections,
+
+ - When `curl_easy_cleanup()` is called, we close all still opened connections,
    unless of course the multi interface "owns" the connections.
 
  The curl handle must be re-used in order for the persistent connections to
  work.
 
+<a name="multi"></a>
 multi interface/non-blocking
 ============================
 
@@ -341,6 +428,7 @@ multi interface/non-blocking
  protocols are crappy examples and they are subject for rewrite in the future
  to better fit the libcurl protocol family.
 
+<a name="ssl"></a>
 SSL libraries
 =============
 
@@ -350,36 +438,39 @@ SSL libraries
  in future libcurl versions.
 
  To deal with this internally in the best way possible, we have a generic SSL
- function API as provided by the vtls.[ch] system, and they are the only SSL
- functions we must use from within libcurl. vtls is then crafted to use the
- appropriate lower-level function calls to whatever SSL library that is in
+ function API as provided by the vtls/vtls.[ch] system, and they are the only
+ SSL functions we must use from within libcurl. vtls is then crafted to use
+ the appropriate lower-level function calls to whatever SSL library that is in
  use. For example vtls/openssl.[ch] for the OpenSSL library.
 
+<a name="symbols"></a>
 Library Symbols
 ===============
 
- All symbols used internally in libcurl must use a 'Curl_' prefix if they're
+ All symbols used internally in libcurl must use a `Curl_` prefix if they're
  used in more than a single file. Single-file symbols must be made static.
- Public ("exported") symbols must use a 'curl_' prefix. (There are exceptions,
+ Public ("exported") symbols must use a `curl_` prefix. (There are exceptions,
  but they are to be changed to follow this pattern in future versions.) Public
- API functions are marked with CURL_EXTERN in the public header files so that
- all others can be hidden on platforms where this is possible.
+ API functions are marked with `CURL_EXTERN` in the public header files so
+ that all others can be hidden on platforms where this is possible.
 
+<a name="returncodes"></a>
 Return Codes and Informationals
 ===============================
 
  I've made things simple. Almost every function in libcurl returns a CURLcode,
- that must be CURLE_OK if everything is OK or otherwise a suitable error code
- as the curl/curl.h include file defines. The very spot that detects an error
- must use the Curl_failf() function to set the human-readable error
+ that must be `CURLE_OK` if everything is OK or otherwise a suitable error
+ code as the curl/curl.h include file defines. The very spot that detects an
+ error must use the `Curl_failf()` function to set the human-readable error
  description.
 
  In aiding the user to understand what's happening and to debug curl usage, we
- must supply a fair amount of informational messages by using the Curl_infof()
- function. Those messages are only displayed when the user explicitly asks for
- them. They are best used when revealing information that isn't otherwise
- obvious.
+ must supply a fair amount of informational messages by using the
+ `Curl_infof()` function. Those messages are only displayed when the user
+ explicitly asks for them. They are best used when revealing information that
+ isn't otherwise obvious.
 
+<a name="abi"></a>
 API/ABI
 =======
 
@@ -387,29 +478,31 @@ API/ABI
  that makes it easier to keep a solid API/ABI over time. See docs/libcurl/ABI
  for our promise to users.
 
+<a name="client"></a>
 Client
 ======
 
- main() resides in src/tool_main.c.
+ main() resides in `src/tool_main.c`.
 
- src/tool_hugehelp.c is automatically generated by the mkhelp.pl perl script
+ `src/tool_hugehelp.c` is automatically generated by the mkhelp.pl perl script
  to display the complete "manual" and the src/tool_urlglob.c file holds the
  functions used for the URL-"globbing" support. Globbing in the sense that the
  {} and [] expansion stuff is there.
 
  The client mostly messes around to setup its 'config' struct properly, then
- it calls the curl_easy_*() functions of the library and when it gets back
- control after the curl_easy_perform() it cleans up the library, checks status
- and exits.
+ it calls the `curl_easy_*()` functions of the library and when it gets back
+ control after the `curl_easy_perform()` it cleans up the library, checks
+ status and exits.
 
  When the operation is done, the ourWriteOut() function in src/writeout.c may
  be called to report about the operation. That function is using the
- curl_easy_getinfo() function to extract useful information from the curl
+ `curl_easy_getinfo()` function to extract useful information from the curl
  session.
 
  It may loop and do all this several times if many URLs were specified on the
  command line or config file.
 
+<a name="memorydebug"></a>
 Memory Debugging
 ================
 
@@ -439,6 +532,7 @@ Memory Debugging
  the configure script. When --enable-debug is given both features will be
  enabled, unless some restriction prevents memory tracking from being used.
 
+<a name="test"></a>
 Test Suite
 ==========
 
@@ -456,29 +550,546 @@ Test Suite
  The test suite automatically detects if curl was built with the memory
  debugging enabled, and if it was it will detect memory leaks, too.
 
-Building Releases
-=================
+<a name="asyncdns"></a>
+Asynchronous name resolves
+==========================
+
+ libcurl can be built to do name resolves asynchronously, using either the
+ normal resolver in a threaded manner or by using c-ares.
+
+<a name="cares"></a>
+[c-ares][3]
+------
+
+### Build libcurl to use a c-ares
+
+1. ./configure --enable-ares=/path/to/ares/install
+2. make
+
+### c-ares on win32
+
+ First I compiled c-ares. I changed the default C runtime library to be the
+ single-threaded rather than the multi-threaded (this seems to be required to
+ prevent linking errors later on). Then I simply build the areslib project
+ (the other projects adig/ahost seem to fail under MSVC).
+
+ Next was libcurl. I opened lib/config-win32.h and I added a:
+ `#define USE_ARES 1`
+
+ Next thing I did was I added the path for the ares includes to the include
+ path, and the libares.lib to the libraries.
+
+ Lastly, I also changed libcurl to be single-threaded rather than
+ multi-threaded, again this was to prevent some duplicate symbol errors. I'm
+ not sure why I needed to change everything to single-threaded, but when I
+ didn't I got redefinition errors for several CRT functions (malloc, stricmp,
+ etc.)
+
+<a name="curl_off_t"></a>
+`curl_off_t`
+==========
+
+ curl_off_t is a data type provided by the external libcurl include
+ headers. It is the type meant to be used for the [`curl_easy_setopt()`][1]
+ options that end with LARGE. The type is 64bit large on most modern
+ platforms.
+
+curlx
+=====
+
+ The libcurl source code offers a few functions by source only. They are not
+ part of the official libcurl API, but the source files might be useful for
+ others so apps can optionally compile/build with these sources to gain
+ additional functions.
+
+ We provide them through a single header file for easy access for apps:
+ "curlx.h"
+
+`curlx_strtoofft()`
+-------------------
+   A macro that converts a string containing a number to a curl_off_t number.
+   This might use the curlx_strtoll() function which is provided as source
+   code in strtoofft.c. Note that the function is only provided if no
+   strtoll() (or equivalent) function exist on your platform. If curl_off_t
+   is only a 32 bit number on your platform, this macro uses strtol().
+
+`curlx_tvnow()`
+---------------
+   returns a struct timeval for the current time.
+
+`curlx_tvdiff()`
+--------------
+   returns the difference between two timeval structs, in number of
+   milliseconds.
+
+`curlx_tvdiff_secs()`
+---------------------
+   returns the same as curlx_tvdiff but with full usec resolution (as a
+   double)
+
+Future
+------
+
+ Several functions will be removed from the public curl_ name space in a
+ future libcurl release. They will then only become available as curlx_
+ functions instead. To make the transition easier, we already today provide
+ these functions with the curlx_ prefix to allow sources to get built properly
+ with the new function names. The functions this concerns are:
+
+ - `curlx_getenv`
+ - `curlx_strequal`
+ - `curlx_strnequal`
+ - `curlx_mvsnprintf`
+ - `curlx_msnprintf`
+ - `curlx_maprintf`
+ - `curlx_mvaprintf`
+ - `curlx_msprintf`
+ - `curlx_mprintf`
+ - `curlx_mfprintf`
+ - `curlx_mvsprintf`
+ - `curlx_mvprintf`
+ - `curlx_mvfprintf`
+
+<a name="contentencoding"></a>
+Content Encoding
+================
+
+## About content encodings
+
+ [HTTP/1.1][4] specifies that a client may request that a server encode its
+ response. This is usually used to compress a response using one of a set of
+ commonly available compression techniques. These schemes are 'deflate' (the
+ zlib algorithm), 'gzip' and 'compress'. A client requests that the sever
+ perform an encoding by including an Accept-Encoding header in the request
+ document. The value of the header should be one of the recognized tokens
+ 'deflate', ... (there's a way to register new schemes/tokens, see sec 3.5 of
+ the spec). A server MAY honor the client's encoding request. When a response
+ is encoded, the server includes a Content-Encoding header in the
+ response. The value of the Content-Encoding header indicates which scheme was
+ used to encode the data.
+
+ A client may tell a server that it can understand several different encoding
+ schemes. In this case the server may choose any one of those and use it to
+ encode the response (indicating which one using the Content-Encoding header).
+ It's also possible for a client to attach priorities to different schemes so
+ that the server knows which it prefers. See sec 14.3 of RFC 2616 for more
+ information on the Accept-Encoding header.
+
+## Supported content encodings
+
+ The 'deflate' and 'gzip' content encoding are supported by libcurl. Both
+ regular and chunked transfers work fine.  The zlib library is required for
+ this feature.
+
+## The libcurl interface
+
+ To cause libcurl to request a content encoding use:
+
+  [`curl_easy_setopt`][1](curl, [`CURLOPT_ACCEPT_ENCODING`][5], string)
+
+ where string is the intended value of the Accept-Encoding header.
+
+ Currently, libcurl only understands how to process responses that use the
+ "deflate" or "gzip" Content-Encoding, so the only values for
+ [`CURLOPT_ACCEPT_ENCODING`][5] that will work (besides "identity," which does
+ nothing) are "deflate" and "gzip" If a response is encoded using the
+ "compress" or methods, libcurl will return an error indicating that the
+ response could not be decoded.  If <string> is NULL no Accept-Encoding header
+ is generated.  If <string> is a zero-length string, then an Accept-Encoding
+ header containing all supported encodings will be generated.
+
+ The [`CURLOPT_ACCEPT_ENCODING`][5] must be set to any non-NULL value for
+ content to be automatically decoded.  If it is not set and the server still
+ sends encoded content (despite not having been asked), the data is returned
+ in its raw form and the Content-Encoding type is not checked.
+
+## The curl interface
+
+ Use the [--compressed][6] option with curl to cause it to ask servers to
+ compress responses using any format supported by curl.
+
+<a name="hostip"></a>
+hostip.c explained
+==================
+
+ The main compile-time defines to keep in mind when reading the host*.c source
+ file are these:
+
+## `CURLRES_IPV6`
+
+ this host has getaddrinfo() and family, and thus we use that. The host may
+ not be able to resolve IPv6, but we don't really have to take that into
+ account. Hosts that aren't IPv6-enabled have CURLRES_IPV4 defined.
+
+## `CURLRES_ARES`
+
+ is defined if libcurl is built to use c-ares for asynchronous name
+ resolves. This can be Windows or *nix.
+
+## `CURLRES_THREADED`
+
+ is defined if libcurl is built to use threading for asynchronous name
+ resolves. The name resolve will be done in a new thread, and the supported
+ asynch API will be the same as for ares-builds. This is the default under
+ (native) Windows.
+
+ If any of the two previous are defined, `CURLRES_ASYNCH` is defined too. If
+ libcurl is not built to use an asynchronous resolver, `CURLRES_SYNCH` is
+ defined.
+
+## host*.c sources
+
+ The host*.c sources files are split up like this:
+
+ - hostip.c      - method-independent resolver functions and utility functions
+ - hostasyn.c    - functions for asynchronous name resolves
+ - hostsyn.c     - functions for synchronous name resolves
+ - asyn-ares.c   - functions for asynchronous name resolves using c-ares
+ - asyn-thread.c - functions for asynchronous name resolves using threads
+ - hostip4.c     - IPv4 specific functions
+ - hostip6.c     - IPv6 specific functions
+
+ The hostip.h is the single united header file for all this. It defines the
+ `CURLRES_*` defines based on the config*.h and curl_setup.h defines.
+
+<a name="memoryleak"></a>
+Track Down Memory Leaks
+=======================
+
+## Single-threaded
+
+  Please note that this memory leak system is not adjusted to work in more
+  than one thread. If you want/need to use it in a multi-threaded app. Please
+  adjust accordingly.
+
+
+## Build
+
+  Rebuild libcurl with -DCURLDEBUG (usually, rerunning configure with
+  --enable-debug fixes this). 'make clean' first, then 'make' so that all
+  files actually are rebuilt properly. It will also make sense to build
+  libcurl with the debug option (usually -g to the compiler) so that debugging
+  it will be easier if you actually do find a leak in the library.
+
+  This will create a library that has memory debugging enabled.
+
+## Modify Your Application
+
+  Add a line in your application code:
+
+       `curl_memdebug("dump");`
+
+  This will make the malloc debug system output a full trace of all resource
+  using functions to the given file name. Make sure you rebuild your program
+  and that you link with the same libcurl you built for this purpose as
+  described above.
+
+## Run Your Application
+
+  Run your program as usual. Watch the specified memory trace file grow.
+
+  Make your program exit and use the proper libcurl cleanup functions etc. So
+  that all non-leaks are returned/freed properly.
+
+## Analyze the Flow
+
+  Use the tests/memanalyze.pl perl script to analyze the dump file:
+
+    tests/memanalyze.pl dump
+
+  This now outputs a report on what resources that were allocated but never
+  freed etc. This report is very fine for posting to the list!
+
+  If this doesn't produce any output, no leak was detected in libcurl. Then
+  the leak is mostly likely to be in your code.
+
+<a name="multi_socket"></a>
+`multi_socket`
+==============
+
+ Implementation of the `curl_multi_socket` API
+
+  The main ideas of this API are simply:
+
+   1 - The application can use whatever event system it likes as it gets info
+       from libcurl about what file descriptors libcurl waits for what action
+       on. (The previous API returns `fd_sets` which is very select()-centric).
+
+   2 - When the application discovers action on a single socket, it calls
+       libcurl and informs that there was action on this particular socket and
+       libcurl can then act on that socket/transfer only and not care about
+       any other transfers. (The previous API always had to scan through all
+       the existing transfers.)
+
+  The idea is that [`curl_multi_socket_action()`][7] calls a given callback
+  with information about what socket to wait for what action on, and the
+  callback only gets called if the status of that socket has changed.
+
+  We also added a timer callback that makes libcurl call the application when
+  the timeout value changes, and you set that with [`curl_multi_setopt()`][9]
+  and the [`CURLMOPT_TIMERFUNCTION`][10] option. To get this to work,
+  Internally, there's an added a struct to each easy handle in which we store
+  an "expire time" (if any). The structs are then "splay sorted" so that we
+  can add and remove times from the linked list and yet somewhat swiftly
+  figure out both how long time there is until the next nearest timer expires
+  and which timer (handle) we should take care of now. Of course, the upside
+  of all this is that we get a [`curl_multi_timeout()`][8] that should also
+  work with old-style applications that use [`curl_multi_perform()`][11].
+
+  We created an internal "socket to easy handles" hash table that given
+  a socket (file descriptor) return the easy handle that waits for action on
+  that socket.  This hash is made using the already existing hash code
+  (previously only used for the DNS cache).
+
+  To make libcurl able to report plain sockets in the socket callback, we had
+  to re-organize the internals of the [`curl_multi_fdset()`][12] etc so that
+  the conversion from sockets to `fd_sets` for that function is only done in
+  the last step before the data is returned. I also had to extend c-ares to
+  get a function that can return plain sockets, as that library too returned
+  only `fd_sets` and that is no longer good enough. The changes done to c-ares
+  are available in c-ares 1.3.1 and later.
+
+<a name="structs"></a>
+Structs in libcurl
+==================
+
+This section should cover 7.32.0 pretty accurately, but will make sense even
+for older and later versions as things don't change drastically that often.
+
+## SessionHandle
+
+  The SessionHandle handle struct is the one returned to the outside in the
+  external API as a "CURL *". This is usually known as an easy handle in API
+  documentations and examples.
+
+  Information and state that is related to the actual connection is in the
+  'connectdata' struct. When a transfer is about to be made, libcurl will
+  either create a new connection or re-use an existing one. The particular
+  connectdata that is used by this handle is pointed out by
+  SessionHandle->easy_conn.
+
+  Data and information that regard this particular single transfer is put in
+  the SingleRequest sub-struct.
+
+  When the SessionHandle struct is added to a multi handle, as it must be in
+  order to do any transfer, the ->multi member will point to the `Curl_multi`
+  struct it belongs to. The ->prev and ->next members will then be used by the
+  multi code to keep a linked list of SessionHandle structs that are added to
+  that same multi handle. libcurl always uses multi so ->multi *will* point to
+  a `Curl_multi` when a transfer is in progress.
+
+  ->mstate is the multi state of this particular SessionHandle. When
+  `multi_runsingle()` is called, it will act on this handle according to which
+  state it is in. The mstate is also what tells which sockets to return for a
+  specific SessionHandle when [`curl_multi_fdset()`][12] is called etc.
+
+  The libcurl source code generally use the name 'data' for the variable that
+  points to the SessionHandle.
+
+  When doing multiplexed HTTP/2 transfers, each SessionHandle is associated
+  with an individual stream, sharing the same connectdata struct. Multiplexing
+  makes it even more important to keep things associated with the right thing!
+
+## connectdata
+
+  A general idea in libcurl is to keep connections around in a connection
+  "cache" after they have been used in case they will be used again and then
+  re-use an existing one instead of creating a new as it creates a significant
+  performance boost.
+
+  Each 'connectdata' identifies a single physical connection to a server. If
+  the connection can't be kept alive, the connection will be closed after use
+  and then this struct can be removed from the cache and freed.
+
+  Thus, the same SessionHandle can be used multiple times and each time select
+  another connectdata struct to use for the connection. Keep this in mind, as
+  it is then important to consider if options or choices are based on the
+  connection or the SessionHandle.
+
+  Functions in libcurl will assume that connectdata->data points to the
+  SessionHandle that uses this connection (for the moment).
+
+  As a special complexity, some protocols supported by libcurl require a
+  special disconnect procedure that is more than just shutting down the
+  socket. It can involve sending one or more commands to the server before
+  doing so. Since connections are kept in the connection cache after use, the
+  original SessionHandle may no longer be around when the time comes to shut
+  down a particular connection. For this purpose, libcurl holds a special
+  dummy `closure_handle` SessionHandle in the `Curl_multi` struct to use when
+  needed.
+
+  FTP uses two TCP connections for a typical transfer but it keeps both in
+  this single struct and thus can be considered a single connection for most
+  internal concerns.
+
+  The libcurl source code generally use the name 'conn' for the variable that
+  points to the connectdata.
+
+## Curl_multi
+
+  Internally, the easy interface is implemented as a wrapper around multi
+  interface functions. This makes everything multi interface.
+
+  `Curl_multi` is the multi handle struct exposed as "CURLM *" in external APIs.
+
+  This struct holds a list of SessionHandle structs that have been added to
+  this handle with [`curl_multi_add_handle()`][13]. The start of the list is
+  ->easyp and ->num_easy is a counter of added SessionHandles.
+
+  ->msglist is a linked list of messages to send back when
+  [`curl_multi_info_read()`][14] is called. Basically a node is added to that
+  list when an individual SessionHandle's transfer has completed.
+
+  ->hostcache points to the name cache. It is a hash table for looking up name
+  to IP. The nodes have a limited life time in there and this cache is meant
+  to reduce the time for when the same name is wanted within a short period of
+  time.
+
+  ->timetree points to a tree of SessionHandles, sorted by the remaining time
+  until it should be checked - normally some sort of timeout. Each
+  SessionHandle has one node in the tree.
+
+  ->sockhash is a hash table to allow fast lookups of socket descriptor to
+  which SessionHandle that uses that descriptor. This is necessary for the
+  `multi_socket` API.
+
+  ->conn_cache points to the connection cache. It keeps track of all
+  connections that are kept after use. The cache has a maximum size.
+
+  ->closure_handle is described in the 'connectdata' section.
+
+  The libcurl source code generally use the name 'multi' for the variable that
+  points to the Curl_multi struct.
+
+## Curl_handler
+
+  Each unique protocol that is supported by libcurl needs to provide at least
+  one `Curl_handler` struct. It defines what the protocol is called and what
+  functions the main code should call to deal with protocol specific issues.
+  In general, there's a source file named [protocol].c in which there's a
+  "struct `Curl_handler` `Curl_handler_[protocol]`" declared. In url.c there's
+  then the main array with all individual `Curl_handler` structs pointed to
+  from a single array which is scanned through when a URL is given to libcurl
+  to work with.
+
+  ->scheme is the URL scheme name, usually spelled out in uppercase. That's
+  "HTTP" or "FTP" etc. SSL versions of the protcol need its own `Curl_handler`
+  setup so HTTPS separate from HTTP.
+
+  ->setup_connection is called to allow the protocol code to allocate protocol
+  specific data that then gets associated with that SessionHandle for the rest
+  of this transfer. It gets freed again at the end of the transfer. It will be
+  called before the 'connectdata' for the transfer has been selected/created.
+  Most protocols will allocate its private 'struct [PROTOCOL]' here and assign
+  SessionHandle->req.protop to point to it.
+
+  ->connect_it allows a protocol to do some specific actions after the TCP
+  connect is done, that can still be considered part of the connection phase.
+
+  Some protocols will alter the connectdata->recv[] and connectdata->send[]
+  function pointers in this function.
+
+  ->connecting is similarly a function that keeps getting called as long as the
+  protocol considers itself still in the connecting phase.
+
+  ->do_it is the function called to issue the transfer request. What we call
+  the DO action internally. If the DO is not enough and things need to be kept
+  getting done for the entire DO sequence to complete, ->doing is then usually
+  also provided. Each protocol that needs to do multiple commands or similar
+  for do/doing need to implement their own state machines (see SCP, SFTP,
+  FTP). Some protocols (only FTP and only due to historical reasons) has a
+  separate piece of the DO state called `DO_MORE`.
+
+  ->doing keeps getting called while issuing the transfer request command(s)
+
+  ->done gets called when the transfer is complete and DONE. That's after the
+  main data has been transferred.
+
+  ->do_more gets called during the `DO_MORE` state. The FTP protocol uses this
+  state when setting up the second connection.
+
+  ->`proto_getsock`
+  ->`doing_getsock`
+  ->`domore_getsock`
+  ->`perform_getsock`
+  Functions that return socket information. Which socket(s) to wait for which
+  action(s) during the particular multi state.
+
+  ->disconnect is called immediately before the TCP connection is shutdown.
+
+  ->readwrite gets called during transfer to allow the protocol to do extra
+  reads/writes
+
+  ->defport is the default report TCP or UDP port this protocol uses
+
+  ->protocol is one or more bits in the `CURLPROTO_*` set. The SSL versions
+  have their "base" protocol set and then the SSL variation. Like
+  "HTTP|HTTPS".
+
+  ->flags is a bitmask with additional information about the protocol that will
+  make it get treated differently by the generic engine:
+
+  - `PROTOPT_SSL` - will make it connect and negotiate SSL
+
+  - `PROTOPT_DUAL` - this protocol uses two connections
+
+  - `PROTOPT_CLOSEACTION` - this protocol has actions to do before closing the
+    connection. This flag is no longer used by code, yet still set for a bunch
+    protocol handlers.
+  
+  - `PROTOPT_DIRLOCK` - "direction lock". The SSH protocols set this bit to
+    limit which "direction" of socket actions that the main engine will
+    concern itself about.
+
+  - `PROTOPT_NONETWORK` - a protocol that doesn't use network (read file:)
+
+  - `PROTOPT_NEEDSPWD` - this protocol needs a password and will use a default
+    one unless one is provided
+
+  - `PROTOPT_NOURLQUERY` - this protocol can't handle a query part on the URL
+    (?foo=bar)
+
+## conncache
 
- There's no magic to this. When you consider everything stable enough to be
- released, do this:
+  Is a hash table with connections for later re-use. Each SessionHandle has
+  a pointer to its connection cache. Each multi handle sets up a connection
+  cache that all added SessionHandles share by default.
 
-   1. Tag the source code accordingly.
+## Curl_share
+  
+  The libcurl share API allocates a `Curl_share` struct, exposed to the
+  external API as "CURLSH *".
 
-   2. run the 'maketgz' script (using 'make distcheck' will give you a pretty
-      good view on the status of the current sources). maketgz requires a
-      version number and creates the release archive. maketgz uses 'make dist'
-      for the actual archive building, why you need to fill in the Makefile.am
-      files properly for which files that should be included in the release
-      archives.
+  The idea is that the struct can have a set of own versions of caches and
+  pools and then by providing this struct in the `CURLOPT_SHARE` option, those
+  specific SessionHandles will use the caches/pools that this share handle
+  holds.
+
+  Then individual SessionHandle structs can be made to share specific things
+  that they otherwise wouldn't, such as cookies.
 
-   3. When that's complete, sign the output files.
+  The `Curl_share` struct can currently hold cookies, DNS cache and the SSL
+  session cache.
 
-   4. Upload
+## CookieInfo
 
-   5. Update web site and changelog on site
+  This is the main cookie struct. It holds all known cookies and related
+  information. Each SessionHandle has its own private CookieInfo even when
+  they are added to a multi handle. They can be made to share cookies by using
+  the share API.
 
-   6. Send announcement to the mailing lists
 
- NOTE: you must have curl checked out from git to be able to do a proper
- release build. The release tarballs do not have everything setup in order to
- do releases properly.
+[1]: http://curl.haxx.se/libcurl/c/curl_easy_setopt.html
+[2]: http://curl.haxx.se/libcurl/c/curl_easy_init.html
+[3]: http://c-ares.haxx.se/
+[4]: https://tools.ietf.org/html/rfc7230 "RFC 7230"
+[5]: http://curl.haxx.se/libcurl/c/CURLOPT_ACCEPT_ENCODING.html
+[6]: http://curl.haxx.se/docs/manpage.html#--compressed
+[7]: http://curl.haxx.se/libcurl/c/curl_multi_socket_action.html
+[8]: http://curl.haxx.se/libcurl/c/curl_multi_timeout.html
+[9]: http://curl.haxx.se/libcurl/c/curl_multi_setopt.html
+[10]: http://curl.haxx.se/libcurl/c/CURLMOPT_TIMERFUNCTION.html
+[11]: http://curl.haxx.se/libcurl/c/curl_multi_perform.html
+[12]: http://curl.haxx.se/libcurl/c/curl_multi_fdset.html
+[13]: http://curl.haxx.se/libcurl/c/curl_multi_add_handle.html
+[14]: http://curl.haxx.se/libcurl/c/curl_multi_info_read.html
diff --git a/docs/KNOWN_BUGS b/docs/KNOWN_BUGS
index 09cc07e8c..345dc45d5 100644
--- a/docs/KNOWN_BUGS
+++ b/docs/KNOWN_BUGS
@@ -97,7 +97,7 @@ may have been fixed since this was written!
   something beyond ascii but currently libcurl will only pass in the verbatim
   string the app provides. There are several browsers that already do this
   encoding. The key seems to be the updated draft to RFC2231:
-  http://tools.ietf.org/html/draft-reschke-rfc2231-in-http-02
+  https://tools.ietf.org/html/draft-reschke-rfc2231-in-http-02
 
 66. When using telnet, the time limitation options don't work.
   http://curl.haxx.se/bug/view.cgi?id=846
diff --git a/docs/LIBCURL-STRUCTS b/docs/LIBCURL-STRUCTS
deleted file mode 100644
index 11dee8539..000000000
--- a/docs/LIBCURL-STRUCTS
+++ /dev/null
@@ -1,248 +0,0 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
-Structs in libcurl
-
-This document should cover 7.32.0 pretty accurately, but will make sense even
-for older and later versions as things don't change drastically that often.
-
- 1. The main structs in libcurl
-  1.1 SessionHandle
-  1.2 connectdata
-  1.3 Curl_multi
-  1.4 Curl_handler
-  1.5 conncache
-  1.6 Curl_share
-  1.7 CookieInfo
-
-==============================================================================
-
-1. The main structs in libcurl
-
-  1.1 SessionHandle
-
-  The SessionHandle handle struct is the one returned to the outside in the
-  external API as a "CURL *". This is usually known as an easy handle in API
-  documentations and examples.
-
-  Information and state that is related to the actual connection is in the
-  'connectdata' struct. When a transfer is about to be made, libcurl will
-  either create a new connection or re-use an existing one. The particular
-  connectdata that is used by this handle is pointed out by
-  SessionHandle->easy_conn.
-
-  Data and information that regard this particular single transfer is put in
-  the SingleRequest sub-struct.
-
-  When the SessionHandle struct is added to a multi handle, as it must be in
-  order to do any transfer, the ->multi member will point to the Curl_multi
-  struct it belongs to. The ->prev and ->next members will then be used by the
-  multi code to keep a linked list of SessionHandle structs that are added to
-  that same multi handle. libcurl always uses multi so ->multi *will* point to
-  a Curl_multi when a transfer is in progress.
-
-  ->mstate is the multi state of this particular SessionHandle. When
-  multi_runsingle() is called, it will act on this handle according to which
-  state it is in. The mstate is also what tells which sockets to return for a
-  specific SessionHandle when curl_multi_fdset() is called etc.
-
-  The libcurl source code generally use the name 'data' for the variable that
-  points to the SessionHandle.
-
-  When doing multiplexed HTTP/2 transfers, each SessionHandle is associated
-  with an individual stream, sharing the same connectdata struct. Multiplexing
-  makes it even more important to keep things associated with the right thing!
-
-  1.2 connectdata
-
-  A general idea in libcurl is to keep connections around in a connection
-  "cache" after they have been used in case they will be used again and then
-  re-use an existing one instead of creating a new as it creates a significant
-  performance boost.
-
-  Each 'connectdata' identifies a single physical connection to a server. If
-  the connection can't be kept alive, the connection will be closed after use
-  and then this struct can be removed from the cache and freed.
-
-  Thus, the same SessionHandle can be used multiple times and each time select
-  another connectdata struct to use for the connection. Keep this in mind, as
-  it is then important to consider if options or choices are based on the
-  connection or the SessionHandle.
-
-  Functions in libcurl will assume that connectdata->data points to the
-  SessionHandle that uses this connection (for the moment).
-
-  As a special complexity, some protocols supported by libcurl require a
-  special disconnect procedure that is more than just shutting down the
-  socket. It can involve sending one or more commands to the server before
-  doing so. Since connections are kept in the connection cache after use, the
-  original SessionHandle may no longer be around when the time comes to shut
-  down a particular connection. For this purpose, libcurl holds a special
-  dummy 'closure_handle' SessionHandle in the Curl_multi struct to 
-
-  FTP uses two TCP connections for a typical transfer but it keeps both in
-  this single struct and thus can be considered a single connection for most
-  internal concerns.
-
-  The libcurl source code generally use the name 'conn' for the variable that
-  points to the connectdata.
-
-
-  1.3 Curl_multi
-
-  Internally, the easy interface is implemented as a wrapper around multi
-  interface functions. This makes everything multi interface.
-
-  Curl_multi is the multi handle struct exposed as "CURLM *" in external APIs.
-
-  This struct holds a list of SessionHandle structs that have been added to
-  this handle with curl_multi_add_handle(). The start of the list is ->easyp
-  and ->num_easy is a counter of added SessionHandles.
-
-  ->msglist is a linked list of messages to send back when
-  curl_multi_info_read() is called. Basically a node is added to that list
-  when an individual SessionHandle's transfer has completed.
-
-  ->hostcache points to the name cache. It is a hash table for looking up name
-  to IP. The nodes have a limited life time in there and this cache is meant
-  to reduce the time for when the same name is wanted within a short period of
-  time.
-
-  ->timetree points to a tree of SessionHandles, sorted by the remaining time
-  until it should be checked - normally some sort of timeout. Each
-  SessionHandle has one node in the tree.
-
-  ->sockhash is a hash table to allow fast lookups of socket descriptor to
-  which SessionHandle that uses that descriptor. This is necessary for the
-  multi_socket API.
-
-  ->conn_cache points to the connection cache. It keeps track of all
-  connections that are kept after use. The cache has a maximum size.
-
-  ->closure_handle is described in the 'connectdata' section.
-
-  The libcurl source code generally use the name 'multi' for the variable that
-  points to the Curl_multi struct.
-
-
-  1.4 Curl_handler
-
-  Each unique protocol that is supported by libcurl needs to provide at least
-  one Curl_handler struct. It defines what the protocol is called and what
-  functions the main code should call to deal with protocol specific issues.
-  In general, there's a source file named [protocol].c in which there's a
-  "struct Curl_handler Curl_handler_[protocol]" declared. In url.c there's
-  then the main array with all individual Curl_handler structs pointed to from
-  a single array which is scanned through when a URL is given to libcurl to
-  work with.
-
-  ->scheme is the URL scheme name, usually spelled out in uppercase. That's
-  "HTTP" or "FTP" etc. SSL versions of the protcol need its own Curl_handler
-  setup so HTTPS separate from HTTP.
-
-  ->setup_connection is called to allow the protocol code to allocate protocol
-  specific data that then gets associated with that SessionHandle for the rest
-  of this transfer. It gets freed again at the end of the transfer. It will be
-  called before the 'connectdata' for the transfer has been selected/created.
-  Most protocols will allocate its private 'struct [PROTOCOL]' here and assign
-  SessionHandle->req.protop to point to it.
-
-  ->connect_it allows a protocol to do some specific actions after the TCP
-  connect is done, that can still be considered part of the connection phase.
-
-  Some protocols will alter the connectdata->recv[] and connectdata->send[]
-  function pointers in this function.
-
-  ->connecting is similarly a function that keeps getting called as long as the
-  protocol considers itself still in the connecting phase.
-
-  ->do_it is the function called to issue the transfer request. What we call
-  the DO action internally. If the DO is not enough and things need to be kept
-  getting done for the entire DO sequence to complete, ->doing is then usually
-  also provided. Each protocol that needs to do multiple commands or similar
-  for do/doing need to implement their own state machines (see SCP, SFTP,
-  FTP). Some protocols (only FTP and only due to historical reasons) has a
-  separate piece of the DO state called DO_MORE.
-
-  ->doing keeps getting called while issuing the transfer request command(s)
-
-  ->done gets called when the transfer is complete and DONE. That's after the
-  main data has been transferred.
-
-  ->do_more gets called during the DO_MORE state. The FTP protocol uses this
-  state when setting up the second connection.
-
-  ->proto_getsock
-  ->doing_getsock
-  ->domore_getsock
-  ->perform_getsock
-  Functions that return socket information. Which socket(s) to wait for which
-  action(s) during the particular multi state.
-
-  ->disconnect is called immediately before the TCP connection is shutdown.
-
-  ->readwrite gets called during transfer to allow the protocol to do extra
-  reads/writes
-
-  ->defport is the default report TCP or UDP port this protocol uses
-
-  ->protocol is one or more bits in the CURLPROTO_* set. The SSL versions have
-  their "base" protocol set and then the SSL variation. Like "HTTP|HTTPS".
-
-  ->flags is a bitmask with additional information about the protocol that will
-  make it get treated differently by the generic engine:
-
-    PROTOPT_SSL - will make it connect and negotiate SSL
-
-    PROTOPT_DUAL - this protocol uses two connections
-
-    PROTOPT_CLOSEACTION - this protocol has actions to do before closing the
-    connection. This flag is no longer used by code, yet still set for a bunch
-    protocol handlers.
-  
-    PROTOPT_DIRLOCK - "direction lock". The SSH protocols set this bit to
-    limit which "direction" of socket actions that the main engine will
-    concern itself about.
-
-    PROTOPT_NONETWORK - a protocol that doesn't use network (read file:)
-
-    PROTOPT_NEEDSPWD - this protocol needs a password and will use a default
-    one unless one is provided
-
-    PROTOPT_NOURLQUERY - this protocol can't handle a query part on the URL
-    (?foo=bar)
-
-
-  1.5 conncache
-
-  Is a hash table with connections for later re-use. Each SessionHandle has
-  a pointer to its connection cache. Each multi handle sets up a connection
-  cache that all added SessionHandles share by default.
-
-
-  1.6 Curl_share
-  
-  The libcurl share API allocates a Curl_share struct, exposed to the external
-  API as "CURLSH *".
-
-  The idea is that the struct can have a set of own versions of caches and
-  pools and then by providing this struct in the CURLOPT_SHARE option, those
-  specific SessionHandles will use the caches/pools that this share handle
-  holds.
-
-  Then individual SessionHandle structs can be made to share specific things
-  that they otherwise wouldn't, such as cookies.
-
-  The Curl_share struct can currently hold cookies, DNS cache and the SSL
-  session cache.
-
-  
-  1.7 CookieInfo
-
-  This is the main cookie struct. It holds all known cookies and related
-  information. Each SessionHandle has its own private CookieInfo even when
-  they are added to a multi handle. They can be made to share cookies by using
-  the share API.
diff --git a/docs/LICENSE-MIXING b/docs/LICENSE-MIXING
index a53835c4c..ccb6ada32 100644
--- a/docs/LICENSE-MIXING
+++ b/docs/LICENSE-MIXING
@@ -23,29 +23,29 @@ libcurl http://curl.haxx.se/docs/copyright.html
         Uses an MIT (or Modified BSD)-style license that is as liberal as
         possible.
 
-OpenSSL http://www.openssl.org/source/license.html
+OpenSSL https://www.openssl.org/source/license.html
 
         (May be used for SSL/TLS support) Uses an Original BSD-style license
         with an announcement clause that makes it "incompatible" with GPL. You
         are not allowed to ship binaries that link with OpenSSL that includes
         GPL code (unless that specific GPL code includes an exception for
         OpenSSL - a habit that is growing more and more common). If OpenSSL's
-        licensing is a problem for you, consider using GnuTLS or yassl
-        instead.
+        licensing is a problem for you, consider using another TLS library.
 
 GnuTLS  http://www.gnutls.org/
 
         (May be used for SSL/TLS support) Uses the LGPL[3] license. If this is
-        a problem for you, consider using OpenSSL instead. Also note that
+        a problem for you, consider using another TLS library. Also note that
         GnuTLS itself depends on and uses other libs (libgcrypt and
         libgpg-error) and they too are LGPL- or GPL-licensed.
 
-yassl   http://www.yassl.com/
+WolfSSL   https://www.wolfssl.com/
 
-        (May be used for SSL/TLS support) Uses the GPL[1] license. If this is
-        a problem for you, consider using OpenSSL or GnuTLS instead.
+        (May be used for SSL/TLS support) Uses the GPL[1] license or a
+        propietary license. If this is a problem for you, consider using
+        another TLS library.
 
-NSS     http://www.mozilla.org/projects/security/pki/nss/
+NSS     https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS
 
         (May be used for SSL/TLS support) Is covered by the MPL[4] license,
         the GPL[1] license and the LGPL[3] license. You may choose to license
@@ -57,13 +57,29 @@ axTLS   http://axtls.sourceforge.net/
 
         (May be used for SSL/TLS support) Uses a Modified BSD-style license.
 
+mbedTLS https://tls.mbed.org/
+
+        (May be used for SSL/TLS support) Uses the GPL[1] license or a
+        propietary license. If this is a problem for you, consider using
+        another TLS library.
+
+BoringSSL https://boringssl.googlesource.com/
+
+        (May be used for SSL/TLS support) As an OpenSSL fork, it has the same
+        license as that.
+
+libressl http://www.libressl.org/
+
+        (May be used for SSL/TLS support) As an OpenSSL fork, it has the same
+        license as that.
+
 c-ares  http://daniel.haxx.se/projects/c-ares/license.html
 
         (Used for asynchronous name resolves) Uses an MIT license that is very
         liberal and imposes no restrictions on any other library or part you
         may link with.
 
-zlib    http://www.gzip.org/zlib/zlib_license.html
+zlib    http://www.zlib.net/zlib_license.html
 
         (Used for compressed Transfer-Encoding support) Uses an MIT-style
         license that shouldn't collide with any other library.
@@ -73,12 +89,12 @@ MIT Kerberos http://web.mit.edu/kerberos/www/dist/
         (May be used for GSS support) MIT licensed, that shouldn't collide
         with any other parts.
 
-Heimdal http://www.pdc.kth.se/heimdal/
+Heimdal http://www.h5l.org
 
         (May be used for GSS support) Heimdal is Original BSD licensed with
         the announcement clause.
 
-GNU GSS http://www.gnu.org/software/gss/
+GNU GSS https://www.gnu.org/software/gss/
 
         (May be used for GSS support) GNU GSS is GPL licensed. Note that you
         may not distribute binary curl packages that uses this if you build
@@ -105,10 +121,10 @@ libssh2 http://www.libssh2.org/
         (Used for scp and sftp support) libssh2 uses a Modified BSD-style
         license.
 
-[1] = GPL - GNU General Public License: http://www.gnu.org/licenses/gpl.html
-[2] = http://www.fsf.org/licenses/gpl-faq.html#GPLIncompatibleLibs details on
+[1] = GPL - GNU General Public License: https://www.gnu.org/licenses/gpl.html
+[2] = https://www.gnu.org/licenses/gpl-faq.html#GPLIncompatibleLibs details on
       how to write such an exception to the GPL
 [3] = LGPL - GNU Lesser General Public License:
-      http://www.gnu.org/licenses/lgpl.html
+      https://www.gnu.org/licenses/lgpl.html
 [4] = MPL - Mozilla Public License:
-      http://www.mozilla.org/MPL/
+      https://www.mozilla.org/MPL/
diff --git a/docs/MAIL-ETIQUETTE b/docs/MAIL-ETIQUETTE
index fb503126a..b6c0f4521 100644
--- a/docs/MAIL-ETIQUETTE
+++ b/docs/MAIL-ETIQUETTE
@@ -230,7 +230,7 @@ MAIL ETIQUETTE
   Quote as little as possible. Just enough to provide the context you cannot
   leave out. A lengthy description can be found here:
 
-      http://www.netmeister.org/news/learn2quote.html
+      https://www.netmeister.org/news/learn2quote.html
 
   2.7 Digest
 
diff --git a/docs/Makefile.am b/docs/Makefile.am
index d4a083274..e3e27d333 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -37,7 +37,7 @@ EXTRA_DIST = MANUAL BUGS CONTRIBUTE FAQ FEATURES INTERNALS SSLCERTS	 \
  README.win32 RESOURCES TODO TheArtOfHttpScripting THANKS VERSIONS	 \
  KNOWN_BUGS BINDINGS $(man_MANS) $(HTMLPAGES) HISTORY INSTALL		 \
  $(PDFPAGES) LICENSE-MIXING README.netware DISTRO-DILEMMA INSTALL.devcpp \
- MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS SECURITY RELEASE-PROCEDURE  \
+ MAIL-ETIQUETTE HTTP-COOKIES SECURITY RELEASE-PROCEDURE  \
  SSL-PROBLEMS HTTP2.md ROADMAP.md
 
 MAN2HTML= roffit < $< >$@
diff --git a/docs/RELEASE-PROCEDURE b/docs/RELEASE-PROCEDURE
index cf074dcc6..fc31274e8 100644
--- a/docs/RELEASE-PROCEDURE
+++ b/docs/RELEASE-PROCEDURE
@@ -1,9 +1,3 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
 curl release procedure - how to do a release
 ============================================
 
diff --git a/docs/SSL-PROBLEMS b/docs/SSL-PROBLEMS
index 7ee4d14ee..36502672d 100644
--- a/docs/SSL-PROBLEMS
+++ b/docs/SSL-PROBLEMS
@@ -53,7 +53,7 @@ SSL ciphers
 
   References:
 
-  http://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01
+  https://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01
   
 Allow BEAST
 
diff --git a/docs/THANKS b/docs/THANKS
index 4eaadb31d..89a738ddd 100644
--- a/docs/THANKS
+++ b/docs/THANKS
@@ -36,6 +36,7 @@ Alex Suykov
 Alex Vinnik
 Alex aka WindEagle
 Alexander Beedie
+Alexander Dyagilev
 Alexander Elgert
 Alexander Klauer
 Alexander Kourakos
@@ -55,6 +56,7 @@ Alona Rossen
 Amol Pattekar
 Amr Shahin
 Anatoli Tubman
+Anders Bakken
 Anders Gustafsson
 Anders Havn
 Andi Jahja
@@ -90,6 +92,7 @@ Andy Serpa
 Andy Tsouladze
 Angus Mackay
 Anthon Pang
+Anthony Avina
 Anthony Bryan
 Anthony G. Basile
 Antoine Calando
@@ -104,6 +107,7 @@ Arnaud Ebalard
 Arthur Murray
 Arve Knudsen
 Arvid Norberg
+Ashish Shukla
 Ask Bjørn Hansen
 Askar Safin
 Ates Goral
@@ -131,6 +135,7 @@ Benoit Neil
 Benoit Sigoure
 Bernard Leak
 Bernhard Reutner-Fischer
+Bert Huijben
 Bertrand Demiddelaer
 Bill Doyle
 Bill Egert
@@ -157,8 +162,10 @@ Brandon Wang
 Brendan Jurd
 Brent Beardsley
 Brian Akins
+Brian Chrisman
 Brian Dessent
 Brian J. Murrell
+Brian Prodoehl
 Brian R Duffy
 Brian Ulm
 Brock Noland
@@ -182,6 +189,7 @@ Charles Romestant
 Chen Prog
 Chih-Chung Chang
 Chris "Bob Bob"
+Chris Araman
 Chris Combes
 Chris Conlon
 Chris Deidun
@@ -245,6 +253,7 @@ Daniel Black
 Daniel Cater
 Daniel Egger
 Daniel Johnson
+Daniel Melani
 Daniel Mentz
 Daniel Steinberg
 Daniel Stenberg
@@ -306,6 +315,7 @@ Dirk Manske
 Dmitri Shubin
 Dmitriy Sergeyev
 Dmitry Bartsevich
+Dmitry Eremin-Solenikov
 Dmitry Falko
 Dmitry Kurochkin
 Dmitry Popov
@@ -321,6 +331,7 @@ Douglas Kilpatrick
 Douglas R. Horner
 Douglas Steinwand
 Dov Murik
+Drake Arconis
 Duane Cathey
 Duncan Mac-Vicar Prett
 Dustin Boswell
@@ -335,6 +346,7 @@ Edward Rudd
 Edward Sheldrake
 Eelco Dolstra
 Eetu Ojanen
+Egon Eckert
 Eldar Zaitov
 Ellis Pritchard
 Elmira A Semenova
@@ -390,6 +402,7 @@ François Charlier
 Fred Machado
 Fred New
 Fred Noz
+Fred Stluka
 Frederic Lepied
 Fredrik Thulin
 Gabriel Kuri
@@ -427,6 +440,7 @@ Glenn Sheridan
 Gordon Marler
 Gorilla Maguila
 Grant Erickson
+Grant Pannell
 Greg Hewgill
 Greg Morse
 Greg Onufer
@@ -540,6 +554,7 @@ Jeff Lawson
 Jeff Phillips
 Jeff Pohlmeyer
 Jeff Weber
+Jens Rantil
 Jeremy Friesner
 Jeremy Huddleston
 Jeremy Lin
@@ -567,6 +582,7 @@ Joe Halpin
 Joe Malicki
 Joe Mason
 Joel Chen
+Joel Depooter
 Jofell Gallardo
 Johan Anderson
 Johan Lantz
@@ -705,6 +721,7 @@ Lindley French
 Ling Thio
 Linus Nielsen Feltzing
 Lisa Xu
+Liviu Chircu
 Liza Alenchery
 Lluís Batlle i Rossell
 Loic Dachary
@@ -888,6 +905,7 @@ Oliver Schindler
 Olivier Berger
 Oren Souroujon
 Oren Tirosh
+Orgad Shaneh
 Ori Avtalion
 Oscar Koeroo
 Oscar Norlander
@@ -916,6 +934,7 @@ Paul Marks
 Paul Marquis
 Paul Moore
 Paul Nolan
+Paul Oliver
 Paul Querna
 Paul Saab
 Pavel Cenek
@@ -973,6 +992,7 @@ Quinn Slack
 Radu Simionescu
 Rafa Muyo
 Rafael Sagula
+Rafayel Mkrtchyan
 Rafaël Carré
 Rainer Canavan
 Rainer Jung
@@ -1076,6 +1096,7 @@ Scott Barrett
 Scott Cantor
 Scott Davis
 Scott McCreary
+Sean Boudreau
 Sebastian Rasmussen
 Senthil Raja Velu
 Sergei Nikulov
@@ -1191,6 +1212,7 @@ Tomas Hoger
 Tomas Mlcoch
 Tomas Pospisek
 Tomas Szepe
+Tomas Tomecek
 Tomasz Kojm
 Tomasz Lacki
 Tommie Gannert
@@ -1218,6 +1240,7 @@ Victor Snezhko
 Vijay Panghal
 Vikram Saxena
 Viktor Szakáts
+Ville Skyttä
 Vilmos Nebehaj
 Vincent Bronner
 Vincent Le Normand
diff --git a/docs/THANKS-filter b/docs/THANKS-filter
index 2c5d82553..39a8a4c42 100644
--- a/docs/THANKS-filter
+++ b/docs/THANKS-filter
@@ -49,3 +49,4 @@ s/tetetest tetetest//
 s/Jiří Hruška/Jiri Hruska/
 s/Viktor Szakats/Viktor Szakáts/
 s/Jonathan Cardoso/Jonathan Cardoso Machado/
+s/Linus Nielsen/Linus Nielsen Feltzing/
diff --git a/docs/TODO b/docs/TODO
index 6d0e0854e..a18b0a23f 100644
--- a/docs/TODO
+++ b/docs/TODO
@@ -25,6 +25,7 @@
  1.7 Detect when called from within callbacks
  1.8 Allow SSL (HTTPS) to proxy
  1.9 Cache negative name resolves
+ 1.10 Support IDNA2008
 
  2. libcurl - multi interface
  2.1 More non-blocking
@@ -208,7 +209,7 @@
 
  To prevent local users from snooping on your traffic to the proxy. Supported
  by Chrome already:
- http://www.chromium.org/developers/design-documents/secure-web-proxy
+ https://www.chromium.org/developers/design-documents/secure-web-proxy
 
  ...and by Firefox soon:
  https://bugzilla.mozilla.org/show_bug.cgi?id=378637
@@ -218,6 +219,12 @@
  A name resolve that has failed is likely to fail when made again within a
  short period of time. Currently we only cache positive responses.
 
+1.10 Support IDNA2008
+
+ International Domain Names are supported in libcurl since years back, powered
+ by libidn. libidn implements IDNA2003 which has been superseded by IDNA2008.
+ libidn2 is an existing library offering support for IDNA2008.
+
 
 2. libcurl - multi interface
 
@@ -265,7 +272,7 @@
  HOST is a command for a client to tell which host name to use, to offer FTP
  servers named-based virtual hosting:
 
- http://tools.ietf.org/html/rfc7151
+ https://tools.ietf.org/html/rfc7151
 
 4.2 Alter passive/active on failure and retry
 
@@ -493,7 +500,7 @@ Currently the SMB authentication uses NTLMv1.
 
  DNS-Based Authentication of Named Entities (DANE) is a way to provide SSL
  keys and certs over DNS using DNSSEC as an alternative to the CA model.
- http://www.rfc-editor.org/rfc/rfc6698.txt
+ https://www.rfc-editor.org/rfc/rfc6698.txt
 
  An initial patch was posted by Suresh Krishnaswamy on March 7th 2013
  (http://curl.haxx.se/mail/lib-2013-03/0075.html) but it was a too simple
@@ -523,7 +530,7 @@ Currently the SMB authentication uses NTLMv1.
  Therefore support for the existing -E/--cert and --key options should be
  implemented by supplying a custom certificate to the SChannel APIs, see:
  - Getting a Certificate for Schannel
-   http://msdn.microsoft.com/en-us/library/windows/desktop/aa375447.aspx
+   https://msdn.microsoft.com/en-us/library/windows/desktop/aa375447.aspx
 
 15.2 Add support for custom server certificate validation
 
@@ -534,7 +541,7 @@ Currently the SMB authentication uses NTLMv1.
  Therefore support for the existing --cacert or --capath options should be
  implemented by supplying a custom certificate to the SChannel APIs, see:
  - Getting a Certificate for Schannel
-   http://msdn.microsoft.com/en-us/library/windows/desktop/aa375447.aspx
+   https://msdn.microsoft.com/en-us/library/windows/desktop/aa375447.aspx
 
 15.3 Add support for the --ciphers option
 
@@ -545,7 +552,7 @@ Currently the SMB authentication uses NTLMv1.
  Therefore support for the existing --ciphers option should be implemented
  by mapping the OpenSSL/GnuTLS cipher suites to the SChannel APIs, see
  - Specifying Schannel Ciphers and Cipher Strengths
-   http://msdn.microsoft.com/en-us/library/windows/desktop/aa380161.aspx
+   https://msdn.microsoft.com/en-us/library/windows/desktop/aa380161.aspx
 
 16. SASL
 
diff --git a/docs/VERSIONS b/docs/VERSIONS
index 0670089bd..72a45474d 100644
--- a/docs/VERSIONS
+++ b/docs/VERSIONS
@@ -1,22 +1,18 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
 Version Numbers and Releases
+============================
 
  Curl is not only curl. Curl is also libcurl. They're actually individually
  versioned, but they mostly follow each other rather closely.
 
  The version numbering is always built up using the same system:
 
-        X.Y[.Z]
+        X.Y.Z
+
+  - X is main version number
+  - Y is release number
+  - Z is patch number
 
- Where
-   X is main version number
-   Y is release number
-   Z is patch number
+## Bumping numbers
 
  One of these numbers will get bumped in each new release. The numbers to the
  right of a bumped number will be reset to zero. If Z is zero, it may not be
@@ -57,4 +53,4 @@ Version Numbers and Releases
  release. It makes comparisons with greater than and less than work.
 
  This number is also available as three separate defines:
- LIBCURL_VERSION_MAJOR, LIBCURL_VERSION_MINOR and LIBCURL_VERSION_PATCH.
+ `LIBCURL_VERSION_MAJOR`, `LIBCURL_VERSION_MINOR` and `LIBCURL_VERSION_PATCH`.
diff --git a/docs/curl.1 b/docs/curl.1
index ea2efe48b..11b95d4ef 100644
--- a/docs/curl.1
+++ b/docs/curl.1
@@ -39,8 +39,7 @@ resume, Metalink, and more. As you will see below, the number of features will
 make your head spin!
 
 curl is powered by libcurl for all transfer-related features. See
-.BR libcurl (3)
-for details.
+\fIlibcurl(3)\fP for details.
 .SH URL
 The URL syntax is protocol-dependent. You'll find a detailed description in
 RFC 3986.
@@ -269,11 +268,11 @@ If this option is used several times, the last one will be used.
 .IP "--ciphers <list of ciphers>"
 (SSL) Specifies which ciphers to use in the connection. The list of ciphers
 must specify valid ciphers. Read up on SSL cipher list details on this URL:
-\fIhttp://www.openssl.org/docs/apps/ciphers.html\fP
+\fIhttps://www.openssl.org/docs/apps/ciphers.html\fP
 
 NSS ciphers are done differently than OpenSSL and GnuTLS. The full list of NSS
 ciphers is in the NSSCipherSuite entry at this URL:
-\fIhttp://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP
+\fIhttps://git.fedorahosted.org/cgit/mod_nss.git/plain/docs/mod_nss.html#Directives\fP
 
 If this option is used several times, the last one will be used.
 .IP "--compressed"
@@ -1060,13 +1059,10 @@ in Metalink file, hash check will fail.
 Makes curl scan the \fI.netrc\fP (\fI_netrc\fP on Windows) file in the user's
 home directory for login name and password. This is typically used for FTP on
 Unix. If used with HTTP, curl will enable user authentication. See
-.BR netrc(4)
-or
-.BR ftp(1)
-for details on the file format. Curl will not complain if that file
-doesn't have the right permissions (it should not be either world- or
-group-readable). The environment variable "HOME" is used to find the home
-directory.
+\fInetrc(5)\fP \fIftp(1)\fP for details on the file format. Curl will not
+complain if that file doesn't have the right permissions (it should not be
+either world- or group-readable). The environment variable "HOME" is used to
+find the home directory.
 
 A quick and very simple example of how to setup a \fI.netrc\fP to allow curl
 to FTP to the machine host.domain.com with user name \&'myself' and password
diff --git a/docs/examples/10-at-a-time.c b/docs/examples/10-at-a-time.c
index 5d95a8a89..f43dc75e0 100644
--- a/docs/examples/10-at-a-time.c
+++ b/docs/examples/10-at-a-time.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,9 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* Example application source code using the multi interface to download many
- * files, but with a capped maximum amount of simultaneous transfers.
- *
+/* <DESC>
+ * Source code using the multi interface to download many
+ * files, with a capped maximum amount of simultaneous transfers.
+ * </DESC>
  * Written by Michael Wallner
  */
 
diff --git a/docs/examples/anyauthput.c b/docs/examples/anyauthput.c
index b89dca2e1..2962645b9 100644
--- a/docs/examples/anyauthput.c
+++ b/docs/examples/anyauthput.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,11 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * HTTP PUT upload with authentiction using "any" method. libcurl picks the
+ * one the server supports/wants.
+ * </DESC>
+ */
 #include <stdio.h>
 #include <fcntl.h>
 #ifdef WIN32
diff --git a/docs/examples/asiohiper.cpp b/docs/examples/asiohiper.cpp
index eb5cd0386..ff4134856 100644
--- a/docs/examples/asiohiper.cpp
+++ b/docs/examples/asiohiper.cpp
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 2012 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 2012 - 2015, 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
@@ -20,11 +20,11 @@
  *
  ***************************************************************************/
 
+/* <DESC>
+ * demonstrate the use of multi socket interface with boost::asio
+ * </DESC>
+ */
 /*
- * file: asiohiper.cpp
- * Example program to demonstrate the use of multi socket interface
- * with boost::asio
- *
  * This program is in c++ and uses boost::asio instead of libevent/libev.
  * Requires boost::asio, boost::bind and boost::system
  *
diff --git a/docs/examples/cacertinmem.c b/docs/examples/cacertinmem.c
index 30a5153a8..67fd382b1 100644
--- a/docs/examples/cacertinmem.c
+++ b/docs/examples/cacertinmem.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,17 +19,11 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* Example using a "in core" PEM certificate to retrieve a https page.
- * Written by Theo Borm
+/* <DESC>
+ * CA cert in memory with OpenSSL to get a HTTPS page.
+ * </DESC>
  */
 
-/* on a netBSD system with OPENSSL& LIBCURL installed from
- * pkgsrc (using default paths) this program can be compiled using:
- * gcc -I/usr/pkg/include -L/usr/pkg/lib -lcurl -Wl,-R/usr/pkg/lib -lssl
- * -lcrypto -lz -o curlcacerttest curlcacerttest.c
- * on other operating systems you may want to change paths to headers
- * and libraries
-*/
 #include <openssl/ssl.h>
 #include <curl/curl.h>
 #include <stdio.h>
diff --git a/docs/examples/certinfo.c b/docs/examples/certinfo.c
index ac0109b07..7ec70ee1c 100644
--- a/docs/examples/certinfo.c
+++ b/docs/examples/certinfo.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * Extract lots of TLS certificate info.
+ * </DESC>
+ */
 #include <stdio.h>
 
 #include <curl/curl.h>
diff --git a/docs/examples/chkspeed.c b/docs/examples/chkspeed.c
index 31949b892..bae8ea6b8 100644
--- a/docs/examples/chkspeed.c
+++ b/docs/examples/chkspeed.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * Show transfer timing info after download completes.
+ * </DESC>
+ */
 /* Example source code to show how the callback function can be used to
  * download data into a chunk of memory instead of storing it in a file.
  * After successful download we use curl_easy_getinfo() calls to get the
diff --git a/docs/examples/cookie_interface.c b/docs/examples/cookie_interface.c
index 28ee7817c..b67051c79 100644
--- a/docs/examples/cookie_interface.c
+++ b/docs/examples/cookie_interface.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,7 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* This example shows usage of simple cookie interface. */
+/* <DESC>
+ * Import and export cookies with COOKIELIST.
+ * </DESC>
+ */
 
 #include <stdio.h>
 #include <string.h>
diff --git a/docs/examples/curlgtk.c b/docs/examples/curlgtk.c
index 8cb9914c6..df6b419f2 100644
--- a/docs/examples/curlgtk.c
+++ b/docs/examples/curlgtk.c
@@ -5,9 +5,12 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
+ *  Copyright (c) 2000 David Odin (aka DindinX) for MandrakeSoft
+ */
+/* <DESC>
+ * use the libcurl in a gtk-threaded application
+ * </DESC>
  */
-/* Copyright (c) 2000 David Odin (aka DindinX) for MandrakeSoft */
-/* an attempt to use the curl library in concert with a gtk-threaded application */
 
 #include <stdio.h>
 #include <gtk/gtk.h>
diff --git a/docs/examples/curlx.c b/docs/examples/curlx.c
index c68cf0ddb..9bfb0cbd8 100644
--- a/docs/examples/curlx.c
+++ b/docs/examples/curlx.c
@@ -9,7 +9,10 @@
   certificate presented during ssl session establishment.
 
 */
-
+/* <DESC>
+ * demonstrates use of SSL context callback, requires OpenSSL
+ * </DESC>
+ */
 
 /*
  * Copyright (c) 2003 The OpenEvidence Project.  All rights reserved.
diff --git a/docs/examples/debug.c b/docs/examples/debug.c
index 36dd80d70..6baab4405 100644
--- a/docs/examples/debug.c
+++ b/docs/examples/debug.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * Show how CURLOPT_DEBUGFUNCTION can be used.
+ * </DESC>
+ */
 #include <stdio.h>
 #include <curl/curl.h>
 
diff --git a/docs/examples/evhiperfifo.c b/docs/examples/evhiperfifo.c
index e03801d8c..5a60c8d2c 100644
--- a/docs/examples/evhiperfifo.c
+++ b/docs/examples/evhiperfifo.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * multi socket interface together with libev
+ * </DESC>
+ */
 /* Example application source code using the multi socket interface to
  * download many files at once.
  *
diff --git a/docs/examples/externalsocket.c b/docs/examples/externalsocket.c
index 5486d1255..cae5ccc72 100644
--- a/docs/examples/externalsocket.c
+++ b/docs/examples/externalsocket.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,9 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/*
- * This is an example demonstrating how an application can pass in a custom
+/* <DESC>
+ * An example demonstrating how an application can pass in a custom
  * socket to libcurl to use. This example also handles the connect itself.
+ * </DESC>
  */
 #include <stdio.h>
 #include <string.h>
diff --git a/docs/examples/fileupload.c b/docs/examples/fileupload.c
index 665eca0af..b695a2a61 100644
--- a/docs/examples/fileupload.c
+++ b/docs/examples/fileupload.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * Upload to a file:// URL
+ * </DESC>
+ */
 #include <stdio.h>
 #include <curl/curl.h>
 #include <sys/stat.h>
diff --git a/docs/examples/fopen.c b/docs/examples/fopen.c
index 0aad0abf5..de9ce19a6 100644
--- a/docs/examples/fopen.c
+++ b/docs/examples/fopen.c
@@ -42,6 +42,10 @@
  *
  * This example requires libcurl 7.9.7 or later.
  */
+/* <DESC>
+ * implements an fopen() abstraction allowing reading from URLs
+ * </DESC>
+ */
 
 #include <stdio.h>
 #include <string.h>
diff --git a/docs/examples/ftp-wildcard.c b/docs/examples/ftp-wildcard.c
index d175ddfdc..ae0855cb8 100644
--- a/docs/examples/ftp-wildcard.c
+++ b/docs/examples/ftp-wildcard.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * FTP wildcard pattern matching
+ * </DESC>
+ */
 #include <curl/curl.h>
 #include <stdio.h>
 
diff --git a/docs/examples/ftpget.c b/docs/examples/ftpget.c
index 285283f72..8ec7d7336 100644
--- a/docs/examples/ftpget.c
+++ b/docs/examples/ftpget.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -23,11 +23,9 @@
 
 #include <curl/curl.h>
 
-/*
- * This is an example showing how to get a single file from an FTP server.
- * It delays the actual destination file creation until the first write
- * callback so that it won't create an empty file in case the remote file
- * doesn't exist or something else fails.
+/* <DESC>
+ * Get a single file from an FTP server.
+ * </DESC>
  */
 
 struct FtpFile {
diff --git a/docs/examples/ftpgetinfo.c b/docs/examples/ftpgetinfo.c
index dfdcf78b7..baea7d8e1 100644
--- a/docs/examples/ftpgetinfo.c
+++ b/docs/examples/ftpgetinfo.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -24,9 +24,9 @@
 
 #include <curl/curl.h>
 
-/*
- * This is an example showing how to check a single file's size and mtime
- * from an FTP server.
+/* <DESC>
+ * Checks a single file's size and mtime from an FTP server.
+ * </DESC>
  */
 
 static size_t throw_away(void *ptr, size_t size, size_t nmemb, void *data)
diff --git a/docs/examples/ftpgetresp.c b/docs/examples/ftpgetresp.c
index dcb296adf..76c512bb3 100644
--- a/docs/examples/ftpgetresp.c
+++ b/docs/examples/ftpgetresp.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -23,13 +23,11 @@
 
 #include <curl/curl.h>
 
-/*
- * Similar to ftpget.c but this also stores the received response-lines
+/* <DESC>
+ * Similar to ftpget.c but also stores the received response-lines
  * in a separate file using our own callback!
- *
- * This functionality was introduced in libcurl 7.9.3.
+ * </DESC>
  */
-
 static size_t
 write_response(void *ptr, size_t size, size_t nmemb, void *data)
 {
diff --git a/docs/examples/ftpsget.c b/docs/examples/ftpsget.c
index dae453482..2c1fd3e99 100644
--- a/docs/examples/ftpsget.c
+++ b/docs/examples/ftpsget.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -24,11 +24,9 @@
 
 #include <curl/curl.h>
 
-/*
- * This is an example showing how to get a single file from an FTPS server.
- * It delays the actual destination file creation until the first write
- * callback so that it won't create an empty file in case the remote file
- * doesn't exist or something else fails.
+/* <DESC>
+ * Get a single file from an FTPS server.
+ * </DESC>
  */
 
 struct FtpFile {
diff --git a/docs/examples/ftpupload.c b/docs/examples/ftpupload.c
index e79f8d842..b4fc79f99 100644
--- a/docs/examples/ftpupload.c
+++ b/docs/examples/ftpupload.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -33,11 +33,10 @@
 #include <unistd.h>
 #endif
 
-/*
- * This example shows an FTP upload, with a rename of the file just after
- * a successful upload.
- *
- * Example based on source code provided by Erick Nuwendam. Thanks!
+/* <DESC>
+ * Performs an FTP upload and renames the file just after a successful
+ * transfer.
+ * </DESC>
  */
 
 #define LOCAL_FILE      "/tmp/uploadthis.txt"
diff --git a/docs/examples/ftpuploadresume.c b/docs/examples/ftpuploadresume.c
index 55b8986c7..1a24f7cbd 100644
--- a/docs/examples/ftpuploadresume.c
+++ b/docs/examples/ftpuploadresume.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,13 +19,9 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* Upload to FTP, resuming failed transfers
- *
- * Compile for MinGW like this:
- *  gcc -Wall -pedantic -std=c99 ftpuploadwithresume.c -o ftpuploadresume.exe
- *  -lcurl -lmsvcr70
- *
- * Written by Philip Bock
+/* <DESC>
+ * Upload to FTP, resuming failed transfers.
+ * </DESC>
  */
 
 #include <stdlib.h>
diff --git a/docs/examples/getinfo.c b/docs/examples/getinfo.c
index acbe1e1af..7f578df43 100644
--- a/docs/examples/getinfo.c
+++ b/docs/examples/getinfo.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * Use getinfo to get content-type after completed transfer.
+ * </DESC>
+ */
 #include <stdio.h>
 #include <curl/curl.h>
 
@@ -27,18 +31,14 @@ int main(void)
   CURL *curl;
   CURLcode res;
 
-  /* http://curl.haxx.se/libcurl/c/curl_easy_init.html */
   curl = curl_easy_init();
   if(curl) {
-    /* http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTURL */
     curl_easy_setopt(curl, CURLOPT_URL, "http://www.example.com/");
-    /* http://curl.haxx.se/libcurl/c/curl_easy_perform.html */
     res = curl_easy_perform(curl);
 
     if(CURLE_OK == res) {
       char *ct;
       /* ask for the content-type */
-      /* http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html */
       res = curl_easy_getinfo(curl, CURLINFO_CONTENT_TYPE, &ct);
 
       if((CURLE_OK == res) && ct)
@@ -46,7 +46,6 @@ int main(void)
     }
 
     /* always cleanup */
-    /* http://curl.haxx.se/libcurl/c/curl_easy_cleanup.html */
     curl_easy_cleanup(curl);
   }
   return 0;
diff --git a/docs/examples/getinmemory.c b/docs/examples/getinmemory.c
index a1c21404d..2cf201e96 100644
--- a/docs/examples/getinmemory.c
+++ b/docs/examples/getinmemory.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,8 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* Example source code to show how the callback function can be used to
- * download data into a chunk of memory instead of storing it in a file.
+/* <DESC>
+ * Shows how the write callback function can be used to download data into a
+ * chunk of memory instead of storing it in a file.
+ * </DESC>
  */
 
 #include <stdio.h>
@@ -34,7 +36,6 @@ struct MemoryStruct {
   size_t size;
 };
 
-
 static size_t
 WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
 {
@@ -55,7 +56,6 @@ WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
   return realsize;
 }
 
-
 int main(void)
 {
   CURL *curl_handle;
diff --git a/docs/examples/ghiper.c b/docs/examples/ghiper.c
index 7571ffa3d..0621d3eef 100644
--- a/docs/examples/ghiper.c
+++ b/docs/examples/ghiper.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * multi socket API usage together with with glib2
+ * </DESC>
+ */
 /* Example application source code using the multi socket interface to
  * download many files at once.
  *
diff --git a/docs/examples/hiperfifo.c b/docs/examples/hiperfifo.c
index 84035aa2c..63614f7d4 100644
--- a/docs/examples/hiperfifo.c
+++ b/docs/examples/hiperfifo.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,6 +19,10 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
+/* <DESC>
+ * multi socket API usage with libevent 2
+ * </DESC>
+ */
 /* Example application source code using the multi socket interface to
    download many files at once.
 
diff --git a/docs/examples/href_extractor.c b/docs/examples/href_extractor.c
index c11325d2e..f2c324e3c 100644
--- a/docs/examples/href_extractor.c
+++ b/docs/examples/href_extractor.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 2012 - 2015, 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
@@ -20,13 +20,13 @@
  *
  ***************************************************************************/
 
+/* <DESC>
+ * Uses the "Streaming HTML parser" to extract the href pieces in a streaming
+ * manner from a downloaded HTML.
+ * </DESC>
+ */
 /*
- * This example uses the "Streaming HTML parser" to extract the href pieces in
- * a streaming manner from a downloaded HTML. Kindly donated by Michał
- * Kowalczyk.
- *
- * The parser is found at
- * http://code.google.com/p/htmlstreamparser/
+ * The HTML parser is found at http://code.google.com/p/htmlstreamparser/
  */
 
 #include <stdio.h>
diff --git a/docs/examples/htmltidy.c b/docs/examples/htmltidy.c
index a36e331bf..c1d9508da 100644
--- a/docs/examples/htmltidy.c
+++ b/docs/examples/htmltidy.c
@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -19,13 +19,12 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* Download a document and use libtidy to parse the HTML.
- * Written by Jeff Pohlmeyer
- *
+/* <DESC>
+ * Download a document and use libtidy to parse the HTML.
+ * </DESC>
+ */
+/*
  * LibTidy => http://tidy.sourceforge.net
- *
- * gcc -Wall -I/usr/local/include tidycurl.c -lcurl -ltidy -o tidycurl
- *
  */
 
 #include <stdio.h>
diff --git a/docs/libcurl/curl_easy_cleanup.3 b/docs/libcurl/curl_easy_cleanup.3
index 403bfd35a..e8cd55095 100644
--- a/docs/libcurl/curl_easy_cleanup.3
+++ b/docs/libcurl/curl_easy_cleanup.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, 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
@@ -63,5 +63,6 @@ if(curl) {
 }
 .fi
 .SH "SEE ALSO"
-.BR curl_easy_init "(3), "
-
+.BR curl_easy_init "(3), " curl_easy_duphandle "(3), "
+.BR curl_easy_reset "(3), "
+.BR curl_multi_cleanup "(3), " curl_multi_remove_handle "(3) "
diff --git a/docs/libcurl/curl_easy_duphandle.3 b/docs/libcurl/curl_easy_duphandle.3
index 080723a1b..34cba58c4 100644
--- a/docs/libcurl/curl_easy_duphandle.3
+++ b/docs/libcurl/curl_easy_duphandle.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, 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
@@ -47,4 +47,6 @@ in a synchronous way, the input handle may not be in use when cloned.
 If this function returns NULL, something went wrong and no valid handle was
 returned.
 .SH "SEE ALSO"
-.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_global_init "(3)"
+.BR curl_easy_init "(3)," curl_easy_cleanup "(3)," curl_easy_reset "(3),"
+.BR curl_global_init "(3)"
+
diff --git a/docs/libcurl/curl_easy_setopt.3 b/docs/libcurl/curl_easy_setopt.3
index 4e5b8dec1..a9a6230f2 100644
--- a/docs/libcurl/curl_easy_setopt.3
+++ b/docs/libcurl/curl_easy_setopt.3
@@ -50,6 +50,8 @@ really \fICURLOPT_POSTFIELDS(3)\fP, but the alternative that copies the string
 \fICURLOPT_COPYPOSTFIELDS(3)\fP has some usage characteristics you need to
 read up on.
 
+The order in which the options are set does not matter.
+
 Before version 7.17.0, strings were not copied. Instead the user was forced
 keep them available until libcurl no longer needed them.
 
@@ -291,6 +293,8 @@ Disable Content decoding. See \fICURLOPT_HTTP_CONTENT_DECODING(3)\fP
 Disable Transfer decoding. See \fICURLOPT_HTTP_TRANSFER_DECODING(3)\fP
 .IP CURLOPT_EXPECT_100_TIMEOUT_MS
 100-continue timeout. See \fICURLOPT_EXPECT_100_TIMEOUT_MS(3)\fP
+.IP CURLOPT_PIPEWAIT
+Wait on connection to pipeline on it. See \fICURLOPT_PIPEWAIT(3)\fP
 .SH SMTP OPTIONS
 .IP CURLOPT_MAIL_FROM
 Address of the sender. See \fICURLOPT_MAIL_FROM(3)\fP
diff --git a/docs/libcurl/curl_multi_info_read.3 b/docs/libcurl/curl_multi_info_read.3
index bdf89863f..03be341b2 100644
--- a/docs/libcurl/curl_multi_info_read.3
+++ b/docs/libcurl/curl_multi_info_read.3
@@ -69,6 +69,7 @@ that just completed.
 
 At this point, there are no other \fBmsg\fP types defined.
 .SH EXAMPLE
+.nf
 struct CURLMsg *m;
 
 /* call curl_multi_perform or curl_multi_socket_action first, then loop
@@ -84,7 +85,7 @@ do {
     curl_easy_cleanup(e);
   }
 } while(m);
-
+.fi
 .SH "RETURN VALUE"
 A pointer to a filled-in struct, or NULL if it failed or ran out of
 structs. It also writes the number of messages left in the queue (after this
diff --git a/docs/libcurl/libcurl-errors.3 b/docs/libcurl/libcurl-errors.3
index 07091b5e5..3828996f8 100644
--- a/docs/libcurl/libcurl-errors.3
+++ b/docs/libcurl/libcurl-errors.3
@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2015, 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
@@ -74,7 +74,7 @@ After having sent the FTP password to the server, libcurl expects a proper
 reply. This error code indicates that an unexpected code was returned.
 .IP "CURLE_FTP_ACCEPT_TIMEOUT (12)"
 During an active FTP session while waiting for the server to connect, the
-\fICURLOPT_ACCEPTTIMOUT_MS(3)\fP (or the internal default) timeout expired.
+\fICURLOPT_ACCEPTTIMEOUT_MS(3)\fP (or the internal default) timeout expired.
 .IP "CURLE_FTP_WEIRD_PASV_REPLY (13)"
 libcurl failed to get a sensible result back from the server as a response to
 either a PASV or a EPSV command. The server is flawed.
diff --git a/docs/libcurl/libcurl-multi.3 b/docs/libcurl/libcurl-multi.3
index 770d4a561..f77c366a2 100644
--- a/docs/libcurl/libcurl-multi.3
+++ b/docs/libcurl/libcurl-multi.3
@@ -136,7 +136,7 @@ normal multi interface. Then you also set two callbacks with the
 CURLMOPT_SOCKETFUNCTION and CURLMOPT_TIMERFUNCTION options to
 \fIcurl_multi_setopt(3)\fP. They are two callback functions that libcurl will
 call with information about what sockets to wait for, and for what activity,
-and what the curret timeout time is - if that expires libcurl should be
+and what the current timeout time is - if that expires libcurl should be
 notified.
 
 The multi_socket API is designed to inform your application about which
diff --git a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3 b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
index 577202cfc..2d4dc2350 100644
--- a/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
+++ b/docs/libcurl/opts/CURLOPT_ERRORBUFFER.3
@@ -51,15 +51,33 @@ All
 .nf
 curl = curl_easy_init();
 if(curl) {
-  char error[CURL_ERROR_SIZE]
+  CURLcode res;
+  char errbuf[CURL_ERROR_SIZE];
 
   curl_easy_setopt(curl, CURLOPT_URL, "http://example.com");
 
   /* provide a buffer to store errors in */
-  curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, error);
+  curl_easy_setopt(curl, CURLOPT_ERRORBUFFER, errbuf);
 
-  /* Perform the request */
-  curl_easy_perform(curl);
+  /* set the error buffer as empty before performing a request */
+  errbuf[0] = 0;
+
+  /* perform the request */
+  res = curl_easy_perform(curl);
+
+  /* if the request did not complete correctly, show the error
+  information. if no detailed error information was written to errbuf
+  show the more generic information from curl_easy_strerror instead.
+  */
+  if(res != CURLE_OK) {
+    size_t len = strlen(errbuf);
+    fprintf(stderr, "\\nlibcurl: (%d) ", res);
+    if(len)
+      fprintf(stderr, "%s%s", errbuf,
+              ((errbuf[len - 1] != '\\n') ? "\\n" : ""));
+    else
+      fprintf(stderr, "%s\\n", curl_easy_strerror(res));
+  }
 }
 .fi
 .SH AVAILABILITY
diff --git a/include/curl/curlver.h b/include/curl/curlver.h
index be442eff8..f73d7de52 100644
--- a/include/curl/curlver.h
+++ b/include/curl/curlver.h
@@ -30,12 +30,12 @@
 
 /* This is the version number of the libcurl package from which this header
    file origins: */
-#define LIBCURL_VERSION "7.43.0-DEV"
+#define LIBCURL_VERSION "7.44.0-DEV"
 
 /* The numeric version number is also available "in parts" by using these
    defines: */
 #define LIBCURL_VERSION_MAJOR 7
-#define LIBCURL_VERSION_MINOR 43
+#define LIBCURL_VERSION_MINOR 44
 #define LIBCURL_VERSION_PATCH 0
 
 /* This is the numeric version of the libcurl version number, meant for easier
@@ -57,7 +57,7 @@
    CURL_VERSION_BITS() macro since curl's own configure script greps for it
    and needs it to contain the full number.
 */
-#define LIBCURL_VERSION_NUM 0x072B00
+#define LIBCURL_VERSION_NUM 0x072C00
 
 /*
  * This is the date and time when the full source package was created. The
diff --git a/lib/Makefile.am b/lib/Makefile.am
index 1bef388df..a2c3dc56c 100644
--- a/lib/Makefile.am
+++ b/lib/Makefile.am
@@ -21,9 +21,6 @@
 ###########################################################################
 AUTOMAKE_OPTIONS = foreign nostdinc
 
-DOCS = README.encoding README.memoryleak README.ares README.curlx	\
- README.hostip README.multi_socket README.httpauth README.curl_off_t
-
 CMAKE_DIST = CMakeLists.txt curl_config.h.cmake
 
 EXTRA_DIST = Makefile.b32 Makefile.m32 Makefile.vc6 config-win32.h	\
@@ -31,7 +28,7 @@ EXTRA_DIST = Makefile.b32 Makefile.m32 Makefile.vc6 config-win32.h	\
  makefile.dj config-dos.h libcurl.plist libcurl.rc config-amigaos.h	\
  makefile.amiga Makefile.netware nwlib.c nwos.c config-win32ce.h	\
  config-os400.h setup-os400.h config-symbian.h Makefile.Watcom		\
- config-tpf.h $(DOCS) mk-ca-bundle.pl mk-ca-bundle.vbs $(CMAKE_DIST)	\
+ config-tpf.h mk-ca-bundle.pl mk-ca-bundle.vbs $(CMAKE_DIST)	\
  firefox-db2pem.sh config-vxworks.h Makefile.vxworks checksrc.pl	\
  objnames-test08.sh objnames-test10.sh objnames.inc checksrc.whitelist
 
diff --git a/lib/Makefile.m32 b/lib/Makefile.m32
index ee47d6708..5f88ab724 100644
--- a/lib/Makefile.m32
+++ b/lib/Makefile.m32
@@ -58,7 +58,7 @@ CC	= $(CROSSPREFIX)gcc
 CFLAGS	= $(CURL_CFLAG_EXTRAS) -g -O2 -Wall
 CFLAGS	+= -fno-strict-aliasing
 # comment LDFLAGS below to keep debug info
-LDFLAGS	= -s
+LDFLAGS	= $(CURL_LDFLAG_EXTRAS) -s
 AR	= $(CROSSPREFIX)ar
 RANLIB	= $(CROSSPREFIX)ranlib
 RC	= $(CROSSPREFIX)windres
diff --git a/lib/README.ares b/lib/README.ares
deleted file mode 100644
index 8c77937eb..000000000
--- a/lib/README.ares
+++ /dev/null
@@ -1,69 +0,0 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
-          How To Build libcurl to Use c-ares For Asynch Name Resolves
-          ===========================================================
-
-c-ares:
-  http://c-ares.haxx.se/
-
-NOTE
-  The latest libcurl version requires c-ares 1.6.0 or later.
-
-  Once upon the time libcurl built fine with the "original" ares. That is no
-  longer true. You need to use c-ares.
-
-Build c-ares
-============
-
-1. unpack the c-ares archive
-2. cd c-ares-dir
-3. ./configure
-4. make
-5. make install
-
-Build libcurl to use c-ares in the curl source tree
-===================================================
-
-1. name or symlink the c-ares source directory 'ares' in the curl source
-   directory
-2. ./configure --enable-ares
-
-  Optionally, you can point out the c-ares install tree root with the the
-  --enable-ares option.
-
-3. make
-
-Build libcurl to use an installed c-ares
-========================================
-
-1. ./configure --enable-ares=/path/to/ares/install
-2. make
-
-c-ares on win32
-===============
-(description brought by Dominick Meglio)
-
-First I compiled c-ares. I changed the default C runtime library to be the
-single-threaded rather than the multi-threaded (this seems to be required to
-prevent linking errors later on). Then I simply build the areslib project (the
-other projects adig/ahost seem to fail under MSVC).
-
-Next was libcurl. I opened lib/config-win32.h and I added a:
- #define USE_ARES 1
-
-Next thing I did was I added the path for the ares includes to the include
-path, and the libares.lib to the libraries.
-
-Lastly, I also changed libcurl to be single-threaded rather than
-multi-threaded, again this was to prevent some duplicate symbol errors. I'm
-not sure why I needed to change everything to single-threaded, but when I
-didn't I got redefinition errors for several CRT functions (malloc, stricmp,
-etc.)
-
-I would have modified the MSVC++ project files, but I only have VC.NET and it
-uses a different format than VC6.0 so I didn't want to go and change
-everything and remove VC6.0 support from libcurl.
diff --git a/lib/README.curl_off_t b/lib/README.curl_off_t
deleted file mode 100644
index 923b2774c..000000000
--- a/lib/README.curl_off_t
+++ /dev/null
@@ -1,68 +0,0 @@
-
-   curl_off_t explained
-   ====================
-
-curl_off_t is a data type provided by the external libcurl include headers. It
-is the type meant to be used for the curl_easy_setopt() options that end with
-LARGE. The type is 64bit large on most modern platforms.
-
-Transition from < 7.19.0 to >= 7.19.0
--------------------------------------
-
-Applications that used libcurl before 7.19.0 that are rebuilt with a libcurl
-that is 7.19.0 or later may or may not have to worry about anything of
-this. We have made a significant effort to make the transition really seamless
-and transparent.
-
-You have have to take notice if you are in one of the following situations:
-
-o Your app is using or will after the transition use a libcurl that is built
-  with LFS (large file support) disabled even though your system otherwise
-  supports it.
-
-o Your app is using or will after the transition use a libcurl that doesn't
-  support LFS at all, but your system and compiler support 64bit data types.
-
-In both these cases, the curl_off_t type will now (after the transition) be
-64bit where it previously was 32bit. This will cause a binary incompatibility
-that you MAY need to deal with.
-
-Benefits
---------
-
-This new way has several benefits:
-
-o Platforms without LFS support can still use libcurl to do >32 bit file
-  transfers and range operations etc as long as they have >32 bit data-types
-  supported.
-
-o Applications will no longer easily build with the curl_off_t size
-  mismatched, which has been a very frequent (and annoying) problem with
-  libcurl <= 7.18.2
-
-Historically
-------------
-
-Previously, before 7.19.0, the curl_off_t type would be rather strongly
-connected to the size of the system off_t type, where currently curl_off_t is
-independent of that.
-
-The strong connection to off_t made it troublesome for application authors
-since when they did mistakes, they could get curl_off_t type of different
-sizes in the app vs libcurl, and that caused strange effects that were hard to
-track and detect by users of libcurl.
-
-SONAME
-------
-
-We opted to not bump the soname for the library unconditionally, simply
-because soname bumping is causing a lot of grief and moaning all over the
-community so we try to keep that at minimum. Also, our selected design path
-should be 100% backwards compatible for the vast majority of all libcurl
-users.
-
-Enforce SONAME bump
--------------------
-
-If configure doesn't detect your case where a bump is necessary, re-run it
-with the --enable-soname-bump command line option!
diff --git a/lib/README.curlx b/lib/README.curlx
deleted file mode 100644
index 5375b0d1d..000000000
--- a/lib/README.curlx
+++ /dev/null
@@ -1,61 +0,0 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
-                     Source Code Functions Apps Might Use
-                     ====================================
-
-The libcurl source code offers a few functions by source only. They are not
-part of the official libcurl API, but the source files might be useful for
-others so apps can optionally compile/build with these sources to gain
-additional functions.
-
-We provide them through a single header file for easy access for apps:
-"curlx.h"
-
- curlx_strtoofft()
-
-   A macro that converts a string containing a number to a curl_off_t number.
-   This might use the curlx_strtoll() function which is provided as source
-   code in strtoofft.c. Note that the function is only provided if no
-   strtoll() (or equivalent) function exist on your platform. If curl_off_t
-   is only a 32 bit number on your platform, this macro uses strtol().
-
- curlx_tvnow()
-
-   returns a struct timeval for the current time.
-
- curlx_tvdiff()
-
-   returns the difference between two timeval structs, in number of
-   milliseconds.
-
- curlx_tvdiff_secs()
-
-   returns the same as curlx_tvdiff but with full usec resolution (as a
-   double)
-
-FUTURE
-======
-
- Several functions will be removed from the public curl_ name space in a
- future libcurl release. They will then only become available as curlx_
- functions instead. To make the transition easier, we already today provide
- these functions with the curlx_ prefix to allow sources to get built properly
- with the new function names. The functions this concerns are:
-
-      curlx_getenv
-      curlx_strequal
-      curlx_strnequal
-      curlx_mvsnprintf
-      curlx_msnprintf
-      curlx_maprintf
-      curlx_mvaprintf
-      curlx_msprintf
-      curlx_mprintf
-      curlx_mfprintf
-      curlx_mvsprintf
-      curlx_mvprintf
-      curlx_mvfprintf
diff --git a/lib/README.encoding b/lib/README.encoding
deleted file mode 100644
index 1012bb9ec..000000000
--- a/lib/README.encoding
+++ /dev/null
@@ -1,60 +0,0 @@
-
-                    Content Encoding Support for libcurl
-
-* About content encodings:
-
-HTTP/1.1 [RFC 2616] specifies that a client may request that a server encode
-its response. This is usually used to compress a response using one of a set
-of commonly available compression techniques. These schemes are `deflate' (the
-zlib algorithm), `gzip' and `compress' [sec 3.5, RFC 2616]. A client requests
-that the sever perform an encoding by including an Accept-Encoding header in
-the request document. The value of the header should be one of the recognized
-tokens `deflate', ... (there's a way to register new schemes/tokens, see sec
-3.5 of the spec). A server MAY honor the client's encoding request. When a
-response is encoded, the server includes a Content-Encoding header in the
-response. The value of the Content-Encoding header indicates which scheme was
-used to encode the data.
-
-A client may tell a server that it can understand several different encoding
-schemes. In this case the server may choose any one of those and use it to
-encode the response (indicating which one using the Content-Encoding header).
-It's also possible for a client to attach priorities to different schemes so
-that the server knows which it prefers. See sec 14.3 of RFC 2616 for more
-information on the Accept-Encoding header.
-
-* Current support for content encoding:
-
-Support for the 'deflate' and 'gzip' content encoding are supported by
-libcurl. Both regular and chunked transfers should work fine.  The library
-zlib is required for this feature. 'deflate' support was added by James
-Gallagher, and support for the 'gzip' encoding was added by Dan Fandrich.
-
-* The libcurl interface:
-
-To cause libcurl to request a content encoding use:
-
-    curl_easy_setopt(curl, CURLOPT_ACCEPT_ENCODING, <string>)
-
-where <string> is the intended value of the Accept-Encoding header.
-
-Currently, libcurl only understands how to process responses that use the
-"deflate" or "gzip" Content-Encoding, so the only values for
-CURLOPT_ACCEPT_ENCODING that will work (besides "identity," which does
-nothing) are "deflate" and "gzip" If a response is encoded using the
-"compress" or methods, libcurl will return an error indicating that the
-response could not be decoded.  If <string> is NULL no Accept-Encoding header
-is generated.  If <string> is a zero-length string, then an Accept-Encoding
-header containing all supported encodings will be generated.
-
-The CURLOPT_ACCEPT_ENCODING must be set to any non-NULL value for content to
-be automatically decoded.  If it is not set and the server still sends encoded
-content (despite not having been asked), the data is returned in its raw form
-and the Content-Encoding type is not checked.
-
-* The curl interface:
-
-Use the --compressed option with curl to cause it to ask servers to compress
-responses using any format supported by curl.
-
-James Gallagher <jgallagher@gso.uri.edu>
-Dan Fandrich <dan@coneharvesters.com>
diff --git a/lib/README.hostip b/lib/README.hostip
deleted file mode 100644
index d5688fff1..000000000
--- a/lib/README.hostip
+++ /dev/null
@@ -1,35 +0,0 @@
- hostip.c explained
- ==================
-
- The main COMPILE-TIME DEFINES to keep in mind when reading the host*.c
- source file are these:
-
- CURLRES_IPV6 - this host has getaddrinfo() and family, and thus we use
- that. The host may not be able to resolve IPv6, but we don't really have to
- take that into account. Hosts that aren't IPv6-enabled have CURLRES_IPV4
- defined.
-
- CURLRES_ARES - is defined if libcurl is built to use c-ares for asynchronous
- name resolves. This can be Windows or *nix.
-
- CURLRES_THREADED - is defined if libcurl is built to use threading for
- asynchronous name resolves. The name resolve will be done in a new thread,
- and the supported asynch API will be the same as for ares-builds. This is
- the default under (native) Windows.
-
- If any of the two previous are defined, CURLRES_ASYNCH is defined too. If
- libcurl is not built to use an asynchronous resolver, CURLRES_SYNCH is
- defined.
-
- The host*.c sources files are split up like this:
-
- hostip.c      - method-independent resolver functions and utility functions
- hostasyn.c    - functions for asynchronous name resolves
- hostsyn.c     - functions for synchronous name resolves
- asyn-ares.c   - functions for asynchronous name resolves using c-ares
- asyn-thread.c - functions for asynchronous name resolves using threads
- hostip4.c     - IPv4 specific functions
- hostip6.c     - IPv6 specific functions
-
- The hostip.h is the single united header file for all this. It defines the
- CURLRES_* defines based on the config*.h and curl_setup.h defines.
diff --git a/lib/README.httpauth b/lib/README.httpauth
deleted file mode 100644
index 960504510..000000000
--- a/lib/README.httpauth
+++ /dev/null
@@ -1,74 +0,0 @@
-
-1. PUT/POST without a known auth to use (possibly no auth required):
-
-   (When explicitly set to use a multi-pass auth when doing a POST/PUT,
-   libcurl should immediately go the Content-Length: 0 bytes route to avoid
-   the first send all data phase, step 2. If told to use a single-pass auth,
-   goto step 3.)
-
-   Issue the proper PUT/POST request immediately, with the correct
-   Content-Length and Expect: headers.
-
-   If a 100 response is received or the wait for one times out, start sending
-   the request-body.
-
-   If a 401 (or 407 when talking through a proxy) is received, then:
-
-   If we have "more than just a little" data left to send, close the
-   connection. Exactly what "more than just a little" means will have to be
-   determined. Possibly the current transfer speed should be taken into
-   account as well.
-
-   NOTE: if the size of the POST data is less than MAX_INITIAL_POST_SIZE (when
-   CURLOPT_POSTFIELDS is used), libcurl will send everything in one single
-   write() (all request-headers and request-body) and thus it will
-   unconditionally send the full post data here.
-
-2. PUT/POST with multi-pass auth but not yet completely negotiated:
-
-   Send a PUT/POST request, we know that it will be rejected and thus we claim
-   Content-Length zero to avoid having to send the request-body. (This seems
-   to be what IE does.)
-
-3. PUT/POST as the last step in the auth negotiation, that is when we have
-   what we believe is a completed negotiation:
-
-   Send a full and proper PUT/POST request (again) with the proper
-   Content-Length and a following request-body.
-
-   NOTE: this may very well be the second (or even third) time the whole or at
-   least parts of the request body is sent to the server. Since the data may
-   be provided to libcurl with a callback, we need a way to tell the app that
-   the upload is to be restarted so that the callback will provide data from
-   the start again.  This requires an API method/mechanism that libcurl
-   doesn't have today. See below.
-
-Data Rewind
-
-   It will be troublesome for some apps to deal with a rewind like this in all
-   circumstances. I'm thinking for example when using 'curl' to upload data
-   from stdin. If libcurl ends up having to rewind the reading for a request
-   to succeed, of course a lack of this callback or if it returns failure, will
-   cause the request to fail completely.
-
-   The new callback is set with CURLOPT_IOCTLFUNCTION (in an attempt to add a
-   more generic function that might be used for other IO-related controls in
-   the future):
-
-     curlioerr curl_ioctl(CURL *handle, curliocmd cmd, void *clientp);
-
-   And in the case where the read is to be rewinded, it would be called with a
-   cmd named CURLIOCMD_RESTARTREAD. The callback would then return CURLIOE_OK,
-   if things are fine, or CURLIOE_FAILRESTART if not.
-
-Backwards Compatibility
-
-   The approach used until now, that issues a HEAD on the given URL to trigger
-   the auth negotiation could still be supported and encouraged, but it would
-   be up to the app to first fetch a URL with GET/HEAD to negotiate on, since
-   then a following PUT/POST wouldn't need to negotiate authentication and
-   thus avoid double-sending data.
-
-   Optionally, we keep the current approach if some option is set
-   (CURLOPT_HEADBEFOREAUTH or similar), since it seems to work fairly well for
-   POST on most servers.
diff --git a/lib/README.memoryleak b/lib/README.memoryleak
deleted file mode 100644
index 166177794..000000000
--- a/lib/README.memoryleak
+++ /dev/null
@@ -1,55 +0,0 @@
-                                  _   _ ____  _
-                              ___| | | |  _ \| |
-                             / __| | | | |_) | |
-                            | (__| |_| |  _ <| |___
-                             \___|\___/|_| \_\_____|
-
-             How To Track Down Suspected Memory Leaks in libcurl
-             ===================================================
-
-Single-threaded
-
-  Please note that this memory leak system is not adjusted to work in more
-  than one thread. If you want/need to use it in a multi-threaded app. Please
-  adjust accordingly.
-
-
-Build
-
-  Rebuild libcurl with -DCURLDEBUG (usually, rerunning configure with
-  --enable-debug fixes this). 'make clean' first, then 'make' so that all
-  files actually are rebuilt properly. It will also make sense to build
-  libcurl with the debug option (usually -g to the compiler) so that debugging
-  it will be easier if you actually do find a leak in the library.
-
-  This will create a library that has memory debugging enabled.
-
-Modify Your Application
-
-  Add a line in your application code:
-
-       curl_memdebug("dump");
-
-  This will make the malloc debug system output a full trace of all resource
-  using functions to the given file name. Make sure you rebuild your program
-  and that you link with the same libcurl you built for this purpose as
-  described above.
-
-Run Your Application
-
-  Run your program as usual. Watch the specified memory trace file grow.
-
-  Make your program exit and use the proper libcurl cleanup functions etc. So
-  that all non-leaks are returned/freed properly.
-
-Analyze the Flow
-
-  Use the tests/memanalyze.pl perl script to analyze the dump file:
-
-    tests/memanalyze.pl dump
-
-  This now outputs a report on what resources that were allocated but never
-  freed etc. This report is very fine for posting to the list!
-
-  If this doesn't produce any output, no leak was detected in libcurl. Then
-  the leak is mostly likely to be in your code.
diff --git a/lib/README.multi_socket b/lib/README.multi_socket
deleted file mode 100644
index d91e1d9f2..000000000
--- a/lib/README.multi_socket
+++ /dev/null
@@ -1,53 +0,0 @@
-Implementation of the curl_multi_socket API
-
-  The main ideas of the new API are simply:
-
-   1 - The application can use whatever event system it likes as it gets info
-       from libcurl about what file descriptors libcurl waits for what action
-       on. (The previous API returns fd_sets which is very select()-centric).
-
-   2 - When the application discovers action on a single socket, it calls
-       libcurl and informs that there was action on this particular socket and
-       libcurl can then act on that socket/transfer only and not care about
-       any other transfers. (The previous API always had to scan through all
-       the existing transfers.)
-
-  The idea is that curl_multi_socket_action() calls a given callback with
-  information about what socket to wait for what action on, and the callback
-  only gets called if the status of that socket has changed.
-
-  We also added a timer callback that makes libcurl call the application when
-  the timeout value changes, and you set that with curl_multi_setopt() and the
-  CURLMOPT_TIMERFUNCTION option. To get this to work, Internally, there's an
-  added a struct to each easy handle in which we store an "expire time" (if
-  any). The structs are then "splay sorted" so that we can add and remove
-  times from the linked list and yet somewhat swiftly figure out both how long
-  time there is until the next nearest timer expires and which timer (handle)
-  we should take care of now. Of course, the upside of all this is that we get
-  a curl_multi_timeout() that should also work with old-style applications
-  that use curl_multi_perform().
-
-  We created an internal "socket to easy handles" hash table that given
-  a socket (file descriptor) return the easy handle that waits for action on
-  that socket.  This hash is made using the already existing hash code
-  (previously only used for the DNS cache).
-
-  To make libcurl able to report plain sockets in the socket callback, we had
-  to re-organize the internals of the curl_multi_fdset() etc so that the
-  conversion from sockets to fd_sets for that function is only done in the
-  last step before the data is returned. I also had to extend c-ares to get a
-  function that can return plain sockets, as that library too returned only
-  fd_sets and that is no longer good enough. The changes done to c-ares are
-  available in c-ares 1.3.1 and later.
-
-  We have done a test runs with up to 9000 connections (with a single active
-  one). The curl_multi_socket_action() invoke then takes less than 10
-  microseconds in average (using the read-only-1-byte-at-a-time hack).  We are
-  now below the 60 microseconds "per socket action" goal (the extra 50 is the
-  time libevent needs).
-
-Documentation
-
-    http://curl.haxx.se/libcurl/c/curl_multi_socket_action.html
-    http://curl.haxx.se/libcurl/c/curl_multi_timeout.html
-    http://curl.haxx.se/libcurl/c/curl_multi_setopt.html
diff --git a/lib/cookie.c b/lib/cookie.c
index 94f2a8b85..22730cff4 100644
--- a/lib/cookie.c
+++ b/lib/cookie.c
@@ -1274,9 +1274,8 @@ static int cookie_output(struct CookieInfo *c, const char *dumphere)
           "# http://curl.haxx.se/docs/http-cookies.html\n"
           "# This file was generated by libcurl! Edit at your own risk.\n\n",
           out);
-    co = c->cookies;
 
-    while(co) {
+    for(co = c->cookies; co; co = co->next) {
       if(!co->domain)
         continue;
       format_ptr = get_netscape_format(co);
@@ -1288,7 +1287,6 @@ static int cookie_output(struct CookieInfo *c, const char *dumphere)
       }
       fprintf(out, "%s\n", format_ptr);
       free(format_ptr);
-      co=co->next;
     }
   }
 
@@ -1309,9 +1307,7 @@ struct curl_slist *Curl_cookie_list(struct SessionHandle *data)
       (data->cookies->numcookies == 0))
     return NULL;
 
-  c = data->cookies->cookies;
-
-  while(c) {
+  for(c = data->cookies->cookies; c; c = c->next) {
     if(!c->domain)
       continue;
     line = get_netscape_format(c);
@@ -1326,7 +1322,6 @@ struct curl_slist *Curl_cookie_list(struct SessionHandle *data)
       return NULL;
     }
     list = beg;
-    c = c->next;
   }
 
   return list;
diff --git a/lib/ftp.c b/lib/ftp.c
index de628a2dc..fade092e4 100644
--- a/lib/ftp.c
+++ b/lib/ftp.c
@@ -1887,7 +1887,7 @@ static CURLcode proxy_magic(struct connectdata *conn,
     memset(&http_proxy, 0, sizeof(http_proxy));
     data->req.protop = &http_proxy;
 
-    result = Curl_proxyCONNECT(conn, SECONDARYSOCKET, newhost, newport);
+    result = Curl_proxyCONNECT(conn, SECONDARYSOCKET, newhost, newport, TRUE);
 
     data->req.protop = ftp_save;
 
@@ -3645,7 +3645,7 @@ static CURLcode ftp_do_more(struct connectdata *conn, int *completep)
     if(conn->tunnel_state[SECONDARYSOCKET] == TUNNEL_CONNECT) {
       /* As we're in TUNNEL_CONNECT state now, we know the proxy name and port
          aren't used so we blank their arguments. TODO: make this nicer */
-      result = Curl_proxyCONNECT(conn, SECONDARYSOCKET, NULL, 0);
+      result = Curl_proxyCONNECT(conn, SECONDARYSOCKET, NULL, 0, FALSE);
 
       return result;
     }
diff --git a/lib/http.c b/lib/http.c
index e3cb8370a..f64a56546 100644
--- a/lib/http.c
+++ b/lib/http.c
@@ -427,8 +427,8 @@ static CURLcode http_perhapsrewind(struct connectdata *conn)
     /* figure out how much data we are expected to send */
     switch(data->set.httpreq) {
     case HTTPREQ_POST:
-      if(data->set.postfieldsize != -1)
-        expectsend = data->set.postfieldsize;
+      if(data->state.infilesize != -1)
+        expectsend = data->state.infilesize;
       else if(data->set.postfields)
         expectsend = (curl_off_t)strlen(data->set.postfields);
       break;
@@ -2317,20 +2317,12 @@ CURLcode Curl_http(struct connectdata *conn, bool *done)
                      te
       );
 
-  /*
-   * Free userpwd for Negotiate/NTLM. Cannot reuse as it is associated with
-   * the connection and shouldn't be repeated over it either.
-   */
-  switch (data->state.authhost.picked) {
-  case CURLAUTH_NEGOTIATE:
-  case CURLAUTH_NTLM:
-  case CURLAUTH_NTLM_WB:
-    Curl_safefree(conn->allocptr.userpwd);
-    break;
-  }
+  /* clear userpwd to avoid re-using credentials from re-used connections */
+  Curl_safefree(conn->allocptr.userpwd);
 
   /*
-   * Same for proxyuserpwd
+   * Free proxyuserpwd for Negotiate/NTLM. Cannot reuse as it is associated
+   * with the connection and shouldn't be repeated over it either.
    */
   switch (data->state.authproxy.picked) {
   case CURLAUTH_NEGOTIATE:
@@ -2577,8 +2569,8 @@ CURLcode Curl_http(struct connectdata *conn, bool *done)
       postsize = 0;
     else {
       /* figure out the size of the postfields */
-      postsize = (data->set.postfieldsize != -1)?
-        data->set.postfieldsize:
+      postsize = (data->state.infilesize != -1)?
+        data->state.infilesize:
         (data->set.postfields? (curl_off_t)strlen(data->set.postfields):-1);
     }
 
@@ -2701,7 +2693,7 @@ CURLcode Curl_http(struct connectdata *conn, bool *done)
           return result;
       }
 
-      else if(data->set.postfieldsize) {
+      else if(data->state.infilesize) {
         /* set the upload size to the progress meter */
         Curl_pgrsSetUploadSize(data, postsize?postsize:-1);
 
diff --git a/lib/http_proxy.c b/lib/http_proxy.c
index 5ab9915a6..4373d6284 100644
--- a/lib/http_proxy.c
+++ b/lib/http_proxy.c
@@ -68,7 +68,7 @@ CURLcode Curl_proxy_connect(struct connectdata *conn)
     conn->data->req.protop = &http_proxy;
     connkeep(conn, "HTTP proxy CONNECT");
     result = Curl_proxyCONNECT(conn, FIRSTSOCKET,
-                               conn->host.name, conn->remote_port);
+                               conn->host.name, conn->remote_port, FALSE);
     conn->data->req.protop = prot_save;
     if(CURLE_OK != result)
       return result;
@@ -85,12 +85,16 @@ CURLcode Curl_proxy_connect(struct connectdata *conn)
  * Curl_proxyCONNECT() requires that we're connected to a HTTP proxy. This
  * function will issue the necessary commands to get a seamless tunnel through
  * this proxy. After that, the socket can be used just as a normal socket.
+ *
+ * 'blocking' set to TRUE means that this function will do the entire CONNECT
+ * + response in a blocking fashion. Should be avoided!
  */
 
 CURLcode Curl_proxyCONNECT(struct connectdata *conn,
                            int sockindex,
                            const char *hostname,
-                           int remote_port)
+                           int remote_port,
+                           bool blocking)
 {
   int subversion=0;
   struct SessionHandle *data=conn->data;
@@ -225,12 +229,14 @@ CURLcode Curl_proxyCONNECT(struct connectdata *conn,
       return CURLE_RECV_ERROR;
     }
 
-    if(0 == Curl_socket_ready(tunnelsocket, CURL_SOCKET_BAD, 0))
-      /* return so we'll be called again polling-style */
-      return CURLE_OK;
-    else {
-      DEBUGF(infof(data,
-                   "Read response immediately from proxy CONNECT\n"));
+    if(!blocking) {
+      if(0 == Curl_socket_ready(tunnelsocket, CURL_SOCKET_BAD, 0))
+        /* return so we'll be called again polling-style */
+        return CURLE_OK;
+      else {
+        DEBUGF(infof(data,
+               "Read response immediately from proxy CONNECT\n"));
+      }
     }
 
     /* at this point, the tunnel_connecting phase is over. */
diff --git a/lib/http_proxy.h b/lib/http_proxy.h
index 2b5e9c9b4..9c4f0207d 100644
--- a/lib/http_proxy.h
+++ b/lib/http_proxy.h
@@ -7,7 +7,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2015, 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
@@ -26,7 +26,8 @@
 /* ftp can use this as well */
 CURLcode Curl_proxyCONNECT(struct connectdata *conn,
                            int tunnelsocket,
-                           const char *hostname, int remote_port);
+                           const char *hostname, int remote_port,
+                           bool blocking);
 
 /* Default proxy timeout in milliseconds */
 #define PROXY_TIMEOUT (3600*1000)
@@ -34,7 +35,7 @@ CURLcode Curl_proxyCONNECT(struct connectdata *conn,
 CURLcode Curl_proxy_connect(struct connectdata *conn);
 
 #else
-#define Curl_proxyCONNECT(x,y,z,w) CURLE_NOT_BUILT_IN
+#define Curl_proxyCONNECT(x,y,z,w,v) CURLE_NOT_BUILT_IN
 #define Curl_proxy_connect(x) CURLE_OK
 #endif
 
diff --git a/lib/multi.c b/lib/multi.c
index 85a563d55..d4a00172e 100644
--- a/lib/multi.c
+++ b/lib/multi.c
@@ -400,7 +400,10 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle,
   /* Point to the multi's connection cache */
   data->state.conn_cache = &multi->conn_cache;
 
-  data->state.infilesize = data->set.filesize;
+  if(data->set.httpreq == HTTPREQ_PUT)
+    data->state.infilesize = data->set.filesize;
+  else
+    data->state.infilesize = data->set.postfieldsize;
 
   /* This adds the new entry at the 'end' of the doubly-linked circular
      list of SessionHandle structs to try and maintain a FIFO queue so
@@ -1529,9 +1532,6 @@ static CURLMcode multi_runsingle(struct Curl_multi *multi,
         break;
       }
 
-      DEBUGF(infof(data, "multi_runsingle:%d call Curl_readwrite\n",
-                   __LINE__));
-
       /* read/write data if it is ready to do so */
       result = Curl_readwrite(data->easy_conn, data, &done);
 
diff --git a/lib/rtsp.c b/lib/rtsp.c
index c5ca75723..c30afd39d 100644
--- a/lib/rtsp.c
+++ b/lib/rtsp.c
@@ -322,7 +322,7 @@ static CURLcode rtsp_do(struct connectdata *conn, bool *done)
   if(!p_session_id &&
      (rtspreq & ~(RTSPREQ_OPTIONS | RTSPREQ_DESCRIBE | RTSPREQ_SETUP))) {
     failf(data, "Refusing to issue an RTSP request [%s] without a session ID.",
-          p_request ? p_request : "");
+          p_request);
     return CURLE_BAD_FUNCTION_ARGUMENT;
   }
 
@@ -440,8 +440,7 @@ static CURLcode rtsp_do(struct connectdata *conn, bool *done)
     Curl_add_bufferf(req_buffer,
                      "%s %s RTSP/1.0\r\n" /* Request Stream-URI RTSP/1.0 */
                      "CSeq: %ld\r\n", /* CSeq */
-                     (p_request ? p_request : ""), p_stream_uri,
-                     rtsp->CSeq_sent);
+                     p_request, p_stream_uri, rtsp->CSeq_sent);
   if(result)
     return result;
 
@@ -495,8 +494,8 @@ static CURLcode rtsp_do(struct connectdata *conn, bool *done)
 
     }
     else {
-      postsize = (data->set.postfieldsize != -1)?
-        data->set.postfieldsize:
+      postsize = (data->state.infilesize != -1)?
+        data->state.infilesize:
         (data->set.postfields? (curl_off_t)strlen(data->set.postfields):0);
       data->set.httpreq = HTTPREQ_POST;
     }
diff --git a/lib/security.c b/lib/security.c
index 1bea669d5..014bbf1b8 100644
--- a/lib/security.c
+++ b/lib/security.c
@@ -480,56 +480,54 @@ static CURLcode choose_mech(struct connectdata *conn)
   void *tmp_allocation;
   const struct Curl_sec_client_mech *mech = &Curl_krb5_client_mech;
 
-  do {
-    tmp_allocation = realloc(conn->app_data, mech->size);
-    if(tmp_allocation == NULL) {
-      failf(data, "Failed realloc of size %u", mech->size);
-      mech = NULL;
-      return CURLE_OUT_OF_MEMORY;
-    }
-    conn->app_data = tmp_allocation;
-
-    if(mech->init) {
-      ret = mech->init(conn->app_data);
-      if(ret) {
-        infof(data, "Failed initialization for %s. Skipping it.\n",
-              mech->name);
-        continue;
-      }
+  tmp_allocation = realloc(conn->app_data, mech->size);
+  if(tmp_allocation == NULL) {
+    failf(data, "Failed realloc of size %u", mech->size);
+    mech = NULL;
+    return CURLE_OUT_OF_MEMORY;
+  }
+  conn->app_data = tmp_allocation;
+
+  if(mech->init) {
+    ret = mech->init(conn->app_data);
+    if(ret) {
+      infof(data, "Failed initialization for %s. Skipping it.\n",
+            mech->name);
+      return CURLE_FAILED_INIT;
     }
+  }
 
-    infof(data, "Trying mechanism %s...\n", mech->name);
-    ret = ftp_send_command(conn, "AUTH %s", mech->name);
-    if(ret < 0)
-      /* FIXME: This error is too generic but it is OK for now. */
-      return CURLE_COULDNT_CONNECT;
-
-    if(ret/100 != 3) {
-      switch(ret) {
-      case 504:
-        infof(data, "Mechanism %s is not supported by the server (server "
-                    "returned ftp code: 504).\n", mech->name);
-        break;
-      case 534:
-        infof(data, "Mechanism %s was rejected by the server (server returned "
-                    "ftp code: 534).\n", mech->name);
-        break;
-      default:
-        if(ret/100 == 5) {
-          infof(data, "server does not support the security extensions\n");
-          return CURLE_USE_SSL_FAILED;
-        }
-        break;
+  infof(data, "Trying mechanism %s...\n", mech->name);
+  ret = ftp_send_command(conn, "AUTH %s", mech->name);
+  if(ret < 0)
+    /* FIXME: This error is too generic but it is OK for now. */
+    return CURLE_COULDNT_CONNECT;
+
+  if(ret/100 != 3) {
+    switch(ret) {
+    case 504:
+      infof(data, "Mechanism %s is not supported by the server (server "
+            "returned ftp code: 504).\n", mech->name);
+      break;
+    case 534:
+      infof(data, "Mechanism %s was rejected by the server (server returned "
+            "ftp code: 534).\n", mech->name);
+      break;
+    default:
+      if(ret/100 == 5) {
+        infof(data, "server does not support the security extensions\n");
+        return CURLE_USE_SSL_FAILED;
       }
-      continue;
+      break;
     }
+    return CURLE_LOGIN_DENIED;
+  }
 
-    /* Authenticate */
-    ret = mech->auth(conn->app_data, conn);
+  /* Authenticate */
+  ret = mech->auth(conn->app_data, conn);
 
-    if(ret == AUTH_CONTINUE)
-      continue;
-    else if(ret != AUTH_OK) {
+  if(ret != AUTH_CONTINUE) {
+    if(ret != AUTH_OK) {
       /* Mechanism has dumped the error to stderr, don't error here. */
       return -1;
     }
@@ -545,8 +543,7 @@ static CURLcode choose_mech(struct connectdata *conn)
     /* Set the requested protection level */
     /* BLOCKING */
     (void)sec_set_protection_level(conn);
-
-  } WHILE_FALSE;
+  }
 
   return CURLE_OK;
 }
diff --git a/lib/smb.c b/lib/smb.c
index 8cb350359..d461a712c 100644
--- a/lib/smb.c
+++ b/lib/smb.c
@@ -783,9 +783,15 @@ static CURLcode smb_request_state(struct connectdata *conn, bool *done)
     off = Curl_read16_le(((unsigned char *) msg) +
                          sizeof(struct smb_header) + 13);
     if(len > 0) {
-      result = Curl_client_write(conn, CLIENTWRITE_BODY,
-                                 (char *)msg + off + sizeof(unsigned int),
-                                 len);
+      struct smb_conn *smbc = &conn->proto.smbc;
+      if(off + sizeof(unsigned int) + len > smbc->got) {
+        failf(conn->data, "Invalid input packet");
+        result = CURLE_RECV_ERROR;
+      }
+      else
+        result = Curl_client_write(conn, CLIENTWRITE_BODY,
+                                   (char *)msg + off + sizeof(unsigned int),
+                                   len);
       if(result) {
         req->result = result;
         next_state = SMB_CLOSE;
diff --git a/lib/transfer.c b/lib/transfer.c
index 42d38b51a..28cc61ecc 100644
--- a/lib/transfer.c
+++ b/lib/transfer.c
@@ -1053,9 +1053,6 @@ CURLcode Curl_readwrite(struct connectdata *conn,
     return CURLE_SEND_ERROR;
   }
 
-  DEBUGF(infof(data, "Curl_readwrite: keepon: %x select_res %x\n", k->keepon,
-               select_res));
-
   /* We go ahead and do a read if we have a readable socket or if
      the stream was rewound (in which case we have data in a
      buffer) */
diff --git a/lib/urldata.h b/lib/urldata.h
index 5a2a07d9e..59c704e0d 100644
--- a/lib/urldata.h
+++ b/lib/urldata.h
@@ -324,6 +324,9 @@ struct ssl_connect_data {
   size_t encdata_offset, decdata_offset;
   unsigned char *encdata_buffer, *decdata_buffer;
   unsigned long req_flags, ret_flags;
+  CURLcode recv_unrecoverable_err; /* schannel_recv had an unrecoverable err */
+  bool recv_sspi_close_notify; /* true if connection closed by close_notify */
+  bool recv_connection_closed; /* true if connection closed, regardless how */
 #endif /* USE_SCHANNEL */
 #ifdef USE_DARWINSSL
   SSLContextRef ssl_ctx;
diff --git a/lib/vtls/openssl.c b/lib/vtls/openssl.c
index d1ea5fbf1..37d50cb60 100644
--- a/lib/vtls/openssl.c
+++ b/lib/vtls/openssl.c
@@ -136,6 +136,11 @@
 #define CONF_modules_load_file(a,b,c)
 #endif
 
+#ifdef OPENSSL_IS_BORINGSSL
+/* not present in BoringSSL */
+#define OPENSSL_load_builtin_modules(x)
+#endif
+
 /*
  * Number of bytes to read from the random number seed file. This must be
  * a finite value (because some entropy "files" like /dev/urandom have
@@ -1427,8 +1432,10 @@ static const char *ssl_msg_type(int ssl_ver, int msg)
         return "Client hello";
       case SSL3_MT_SERVER_HELLO:
         return "Server hello";
+#ifdef SSL3_MT_NEWSESSION_TICKET
       case SSL3_MT_NEWSESSION_TICKET:
         return "Newsession Ticket";
+#endif
       case SSL3_MT_CERTIFICATE:
         return "Certificate";
       case SSL3_MT_SERVER_KEY_EXCHANGE:
@@ -2130,10 +2137,9 @@ static CURLcode ossl_connect_step2(struct connectdata *conn, int sockindex)
     else {
       /* untreated error */
       unsigned long errdetail;
-      char error_buffer[256]; /* OpenSSL documents that this must be at least
-                                 256 bytes long. */
+      char error_buffer[256]=""; /* OpenSSL documents that this must be at
+                                    least 256 bytes long. */
       CURLcode result;
-      const char *cert_problem = NULL;
       long lerr;
 
       connssl->connecting_state = ssl_connect_2; /* the connection failed,
@@ -2165,9 +2171,10 @@ static CURLcode ossl_connect_step2(struct connectdata *conn, int sockindex)
                    X509_verify_cert_error_string(lerr));
         }
         else
-          cert_problem = "SSL certificate problem, verify that the CA cert is"
-            " OK.";
-
+          /* strcpy() is fine here as long as the string fits within
+             error_buffer */
+          strcpy(error_buffer,
+                 "SSL certificate problem, check your CA cert");
         break;
       default:
         result = CURLE_SSL_CONNECT_ERROR;
@@ -2188,7 +2195,7 @@ static CURLcode ossl_connect_step2(struct connectdata *conn, int sockindex)
       }
 
       /* Could be a CERT problem */
-      failf(data, "%s%s", cert_problem ? cert_problem : "", error_buffer);
+      failf(data, "%s", error_buffer);
 
       return result;
     }
diff --git a/lib/vtls/schannel.c b/lib/vtls/schannel.c
index b02e42ecc..19aff8f07 100644
--- a/lib/vtls/schannel.c
+++ b/lib/vtls/schannel.c
@@ -268,6 +268,10 @@ schannel_connect_step1(struct connectdata *conn, int sockindex)
   infof(data, "schannel: sent initial handshake data: "
         "sent %zd bytes\n", written);
 
+  connssl->recv_unrecoverable_err = CURLE_OK;
+  connssl->recv_sspi_close_notify = false;
+  connssl->recv_connection_closed = false;
+
   /* continue to second handshake step */
   connssl->connecting_state = ssl_connect_2;
 
@@ -300,6 +304,17 @@ schannel_connect_step2(struct connectdata *conn, int sockindex)
   if(!connssl->cred || !connssl->ctxt)
     return CURLE_SSL_CONNECT_ERROR;
 
+  /* buffer to store previously received and decrypted data */
+  if(connssl->decdata_buffer == NULL) {
+    connssl->decdata_offset = 0;
+    connssl->decdata_length = CURL_SCHANNEL_BUFFER_INIT_SIZE;
+    connssl->decdata_buffer = malloc(connssl->decdata_length);
+    if(connssl->decdata_buffer == NULL) {
+      failf(data, "schannel: unable to allocate memory");
+      return CURLE_OUT_OF_MEMORY;
+    }
+  }
+
   /* buffer to store previously received and encrypted data */
   if(connssl->encdata_buffer == NULL) {
     connssl->encdata_offset = 0;
@@ -403,6 +418,17 @@ schannel_connect_step2(struct connectdata *conn, int sockindex)
       return CURLE_OK;
     }
 
+    /* If the server has requested a client certificate, attempt to continue
+       the handshake without one. This will allow connections to servers which
+       request a client certificate but do not require it. */
+    if(sspi_status == SEC_I_INCOMPLETE_CREDENTIALS &&
+       !(connssl->req_flags & ISC_REQ_USE_SUPPLIED_CREDS)) {
+      connssl->req_flags |= ISC_REQ_USE_SUPPLIED_CREDS;
+      connssl->connecting_state = ssl_connect_2_writing;
+      infof(data, "schannel: a client certificate has been requested\n");
+      return CURLE_OK;
+    }
+
     /* check if the handshake needs to be continued */
     if(sspi_status == SEC_I_CONTINUE_NEEDED || sspi_status == SEC_E_OK) {
       for(i = 0; i < 3; i++) {
@@ -823,8 +849,7 @@ schannel_recv(struct connectdata *conn, int sockindex,
               char *buf, size_t len, CURLcode *err)
 {
   size_t size = 0;
-  ssize_t nread = 0;
-  CURLcode result;
+  ssize_t nread = -1;
   struct SessionHandle *data = conn->data;
   struct ssl_connect_data *connssl = &conn->ssl[sockindex];
   unsigned char *reallocated_buffer;
@@ -833,72 +858,103 @@ schannel_recv(struct connectdata *conn, int sockindex,
   SecBuffer inbuf[4];
   SecBufferDesc inbuf_desc;
   SECURITY_STATUS sspi_status = SEC_E_OK;
+  /* we want the length of the encrypted buffer to be at least large enough
+     that it can hold all the bytes requested and some TLS record overhead. */
+  size_t min_encdata_length = len + CURL_SCHANNEL_BUFFER_FREE_SIZE;
+
+  /****************************************************************************
+   * Don't return or set connssl->recv_unrecoverable_err unless in the cleanup.
+   * The pattern for return error is set *err, optional infof, goto cleanup.
+   *
+   * Our priority is to always return as much decrypted data to the caller as
+   * possible, even if an error occurs. The state of the decrypted buffer must
+   * always be valid. Transfer of decrypted data to the caller's buffer is
+   * handled in the cleanup.
+   */
 
   infof(data, "schannel: client wants to read %zu bytes\n", len);
   *err = CURLE_OK;
 
-  /* buffer to store previously received and decrypted data */
-  if(connssl->decdata_buffer == NULL) {
-    connssl->decdata_offset = 0;
-    connssl->decdata_length = CURL_SCHANNEL_BUFFER_INIT_SIZE;
-    connssl->decdata_buffer = malloc(connssl->decdata_length);
-    if(connssl->decdata_buffer == NULL) {
-      failf(data, "schannel: unable to allocate memory");
-      *err = CURLE_OUT_OF_MEMORY;
-      return -1;
-    }
+  if(len && len <= connssl->decdata_offset) {
+    infof(data, "schannel: enough decrypted data is already available\n");
+    goto cleanup;
   }
+  else if(connssl->recv_unrecoverable_err) {
+    *err = connssl->recv_unrecoverable_err;
+    infof(data, "schannel: an unrecoverable error occurred in a prior call\n");
+    goto cleanup;
+  }
+  else if(connssl->recv_sspi_close_notify) {
+    /* once a server has indicated shutdown there is no more encrypted data */
+    infof(data, "schannel: server indicated shutdown in a prior call\n");
+    goto cleanup;
+  }
+  else if(!len) {
+    /* It's debatable what to return when !len. Regardless we can't return
+    immediately because there may be data to decrypt (in the case we want to
+    decrypt all encrypted cached data) so handle !len later in cleanup.
+    */
+    ; /* do nothing */
+  }
+  else if(!connssl->recv_connection_closed) {
+    /* increase enc buffer in order to fit the requested amount of data */
+    size = connssl->encdata_length - connssl->encdata_offset;
+    if(size < CURL_SCHANNEL_BUFFER_FREE_SIZE ||
+       connssl->encdata_length < min_encdata_length) {
+      reallocated_length = connssl->encdata_offset +
+                           CURL_SCHANNEL_BUFFER_FREE_SIZE;
+      if(reallocated_length < min_encdata_length) {
+        reallocated_length = min_encdata_length;
+      }
+      reallocated_buffer = realloc(connssl->encdata_buffer,
+                                   reallocated_length);
+      if(reallocated_buffer == NULL) {
+        *err = CURLE_OUT_OF_MEMORY;
+        failf(data, "schannel: unable to re-allocate memory");
+        goto cleanup;
+      }
 
-  /* increase buffer in order to fit the requested amount of data */
-  if(connssl->encdata_length - connssl->encdata_offset <
-     CURL_SCHANNEL_BUFFER_FREE_SIZE || connssl->encdata_length < len) {
-    /* increase internal encrypted data buffer */
-    reallocated_length = connssl->encdata_offset +
-      CURL_SCHANNEL_BUFFER_FREE_SIZE;
-    /* make sure that the requested amount of data fits */
-    if(reallocated_length < len) {
-      reallocated_length = len;
-    }
-    reallocated_buffer = realloc(connssl->encdata_buffer,
-                                 reallocated_length);
-
-    if(reallocated_buffer == NULL) {
-      failf(data, "schannel: unable to re-allocate memory");
-      *err = CURLE_OUT_OF_MEMORY;
-      return -1;
-    }
-    else {
       connssl->encdata_buffer = reallocated_buffer;
       connssl->encdata_length = reallocated_length;
+      size = connssl->encdata_length - connssl->encdata_offset;
+      infof(data, "schannel: encdata_buffer resized %zu\n",
+            connssl->encdata_length);
     }
-  }
 
-  /* read encrypted data from socket */
-  infof(data, "schannel: encrypted data buffer: offset %zu length %zu\n",
-        connssl->encdata_offset, connssl->encdata_length);
-  size = connssl->encdata_length - connssl->encdata_offset;
-  if(size > 0) {
+    infof(data, "schannel: encrypted data buffer: offset %zu length %zu\n",
+          connssl->encdata_offset, connssl->encdata_length);
+
+    /* read encrypted data from socket */
     *err = Curl_read_plain(conn->sock[sockindex],
-                           (char *) (connssl->encdata_buffer +
-                                     connssl->encdata_offset),
+                           (char *)(connssl->encdata_buffer +
+                                    connssl->encdata_offset),
                            size, &nread);
-    /* check for received data */
-    if(*err != CURLE_OK) {
-      return -1;
+    if(*err) {
+      nread = -1;
+      if(*err == CURLE_AGAIN)
+        infof(data, "schannel: Curl_read_plain returned CURLE_AGAIN\n");
+      else if(*err == CURLE_RECV_ERROR)
+        infof(data, "schannel: Curl_read_plain returned CURLE_RECV_ERROR\n");
+      else
+        infof(data, "schannel: Curl_read_plain returned error %d\n", *err);
+    }
+    else if(nread == 0) {
+      connssl->recv_connection_closed = true;
+      infof(data, "schannel: server closed the connection\n");
     }
     else if(nread > 0) {
-      /* increase encrypted data buffer offset */
-      connssl->encdata_offset += nread;
+      connssl->encdata_offset += (size_t)nread;
+      infof(data, "schannel: encrypted data got %zd\n", nread);
     }
-    infof(data, "schannel: encrypted data got %zd\n", nread);
   }
 
   infof(data, "schannel: encrypted data buffer: offset %zu length %zu\n",
         connssl->encdata_offset, connssl->encdata_length);
 
-  /* check if we still have some data in our buffers */
+  /* decrypt loop */
   while(connssl->encdata_offset > 0 && sspi_status == SEC_E_OK &&
-        connssl->decdata_offset < len) {
+        (!len || connssl->decdata_offset < len ||
+         connssl->recv_connection_closed)) {
     /* prepare data buffer for DecryptMessage call */
     InitSecBuffer(&inbuf[0], SECBUFFER_DATA, connssl->encdata_buffer,
                   curlx_uztoul(connssl->encdata_offset));
@@ -913,13 +969,6 @@ schannel_recv(struct connectdata *conn, int sockindex,
     sspi_status = s_pSecFn->DecryptMessage(&connssl->ctxt->ctxt_handle,
                                            &inbuf_desc, 0, NULL);
 
-    /* check if we need more data */
-    if(sspi_status == SEC_E_INCOMPLETE_MESSAGE) {
-      infof(data, "schannel: failed to decrypt data, need more data\n");
-      *err = CURLE_AGAIN;
-      return -1;
-    }
-
     /* check if everything went fine (server may want to renegotiate
        or shutdown the connection context) */
     if(sspi_status == SEC_E_OK || sspi_status == SEC_I_RENEGOTIATE ||
@@ -932,7 +981,7 @@ schannel_recv(struct connectdata *conn, int sockindex,
 
         /* increase buffer in order to fit the received amount of data */
         size = inbuf[1].cbBuffer > CURL_SCHANNEL_BUFFER_FREE_SIZE ?
-          inbuf[1].cbBuffer : CURL_SCHANNEL_BUFFER_FREE_SIZE;
+               inbuf[1].cbBuffer : CURL_SCHANNEL_BUFFER_FREE_SIZE;
         if(connssl->decdata_length - connssl->decdata_offset < size ||
            connssl->decdata_length < len) {
           /* increase internal decrypted data buffer */
@@ -943,21 +992,18 @@ schannel_recv(struct connectdata *conn, int sockindex,
           }
           reallocated_buffer = realloc(connssl->decdata_buffer,
                                        reallocated_length);
-
           if(reallocated_buffer == NULL) {
-            failf(data, "schannel: unable to re-allocate memory");
             *err = CURLE_OUT_OF_MEMORY;
-            return -1;
-          }
-          else {
-            connssl->decdata_buffer = reallocated_buffer;
-            connssl->decdata_length = reallocated_length;
+            failf(data, "schannel: unable to re-allocate memory");
+            goto cleanup;
           }
+          connssl->decdata_buffer = reallocated_buffer;
+          connssl->decdata_length = reallocated_length;
         }
 
         /* copy decrypted data to internal buffer */
         size = inbuf[1].cbBuffer;
-        if(size > 0) {
+        if(size) {
           memcpy(connssl->decdata_buffer + connssl->decdata_offset,
                  inbuf[1].pvBuffer, size);
           connssl->decdata_offset += size;
@@ -996,56 +1042,117 @@ schannel_recv(struct connectdata *conn, int sockindex,
       /* check if server wants to renegotiate the connection context */
       if(sspi_status == SEC_I_RENEGOTIATE) {
         infof(data, "schannel: remote party requests renegotiation\n");
-
+        if(*err && *err != CURLE_AGAIN) {
+          infof(data, "schannel: can't renogotiate, an error is pending\n");
+          goto cleanup;
+        }
+        if(connssl->encdata_offset) {
+          *err = CURLE_RECV_ERROR;
+          infof(data, "schannel: can't renogotiate, "
+                      "encrypted data available\n");
+          goto cleanup;
+        }
         /* begin renegotiation */
         infof(data, "schannel: renegotiating SSL/TLS connection\n");
         connssl->state = ssl_connection_negotiating;
         connssl->connecting_state = ssl_connect_2_writing;
-        result = schannel_connect_common(conn, sockindex, FALSE, &done);
-        if(result)
-          *err = result;
-        else {
-          infof(data, "schannel: SSL/TLS connection renegotiated\n");
-          /* now retry receiving data */
-          return schannel_recv(conn, sockindex, buf, len, err);
+        *err = schannel_connect_common(conn, sockindex, FALSE, &done);
+        if(*err) {
+          infof(data, "schannel: renegotiation failed\n");
+          goto cleanup;
         }
+        /* now retry receiving data */
+        sspi_status = SEC_E_OK;
+        infof(data, "schannel: SSL/TLS connection renegotiated\n");
+        continue;
       }
+      /* check if the server closed the connection */
+      else if(sspi_status == SEC_I_CONTEXT_EXPIRED) {
+        /* In Windows 2000 SEC_I_CONTEXT_EXPIRED (close_notify) is not
+           returned so we have to work around that in cleanup. */
+        connssl->recv_sspi_close_notify = true;
+        if(!connssl->recv_connection_closed) {
+          connssl->recv_connection_closed = true;
+          infof(data, "schannel: server closed the connection\n");
+        }
+        goto cleanup;
+      }
+    }
+    else if(sspi_status == SEC_E_INCOMPLETE_MESSAGE) {
+      if(!*err)
+        *err = CURLE_AGAIN;
+      infof(data, "schannel: failed to decrypt data, need more data\n");
+      goto cleanup;
     }
     else {
-      /* something went wrong and we need to return an error */
+      *err = CURLE_RECV_ERROR;
       infof(data, "schannel: failed to read data from server: %s\n",
             Curl_sspi_strerror(conn, sspi_status));
-      *err = CURLE_RECV_ERROR;
-      return -1;
+      goto cleanup;
     }
   }
 
+  infof(data, "schannel: encrypted data buffer: offset %zu length %zu\n",
+        connssl->encdata_offset, connssl->encdata_length);
+
   infof(data, "schannel: decrypted data buffer: offset %zu length %zu\n",
         connssl->decdata_offset, connssl->decdata_length);
 
-  /* copy requested decrypted data to supplied buffer */
+cleanup:
+  /* Warning- there is no guarantee the encdata state is valid at this point */
+  infof(data, "schannel: schannel_recv cleanup\n");
+
+  /* Error if the connection has closed without a close_notify.
+  Behavior here is a matter of debate. We don't want to be vulnerable to a
+  truncation attack however there's some browser precedent for ignoring the
+  close_notify for compatibility reasons.
+  Additionally, Windows 2000 (v5.0) is a special case since it seems it doesn't
+  return close_notify. In that case if the connection was closed we assume it
+  was graceful (close_notify) since there doesn't seem to be a way to tell.
+  */
+  if(len && !connssl->decdata_offset && connssl->recv_connection_closed &&
+     !connssl->recv_sspi_close_notify) {
+    DWORD winver_full, winver_major, winver_minor;
+    winver_full = GetVersion();
+    winver_major = (DWORD)(LOBYTE(LOWORD(winver_full)));
+    winver_minor = (DWORD)(HIBYTE(LOWORD(winver_full)));
+
+    if(winver_major == 5 && winver_minor == 0 && sspi_status == SEC_E_OK)
+      connssl->recv_sspi_close_notify = true;
+    else {
+      *err = CURLE_RECV_ERROR;
+      infof(data, "schannel: server closed abruptly (missing close_notify)\n");
+    }
+  }
+
+  /* Any error other than CURLE_AGAIN is an unrecoverable error. */
+  if(*err && *err != CURLE_AGAIN)
+      connssl->recv_unrecoverable_err = *err;
+
   size = len < connssl->decdata_offset ? len : connssl->decdata_offset;
-  if(size > 0) {
+  if(size) {
     memcpy(buf, connssl->decdata_buffer, size);
-
-    /* move remaining decrypted data forward to the beginning of buffer */
     memmove(connssl->decdata_buffer, connssl->decdata_buffer + size,
             connssl->decdata_offset - size);
     connssl->decdata_offset -= size;
 
-    infof(data, "schannel: decrypted data returned %zd\n", size);
+    infof(data, "schannel: decrypted data returned %zu\n", size);
     infof(data, "schannel: decrypted data buffer: offset %zu length %zu\n",
           connssl->decdata_offset, connssl->decdata_length);
-  }
-  /* check if the server closed the connection, */
-  /* including special check for Windows 2000 Professional */
-  else if(sspi_status == SEC_I_CONTEXT_EXPIRED || (sspi_status == SEC_E_OK &&
-          connssl->encdata_offset && connssl->encdata_buffer[0] == 0x15)) {
-    infof(data, "schannel: server closed the connection\n");
     *err = CURLE_OK;
+    return (ssize_t)size;
   }
 
-  return size;
+  if(!*err && !connssl->recv_connection_closed)
+      *err = CURLE_AGAIN;
+
+  /* It's debatable what to return when !len. We could return whatever error we
+  got from decryption but instead we override here so the return is consistent.
+  */
+  if(!len)
+    *err = CURLE_OK;
+
+  return *err ? -1 : 0;
 }
 
 CURLcode
diff --git a/lib/vtls/schannel.h b/lib/vtls/schannel.h
index e019a8606..532958483 100644
--- a/lib/vtls/schannel.h
+++ b/lib/vtls/schannel.h
@@ -72,6 +72,7 @@
 #define SECBUFFER_ALERT                 17
 #endif
 
+/* Both schannel buffer sizes must be > 0 */
 #define CURL_SCHANNEL_BUFFER_INIT_SIZE   4096
 #define CURL_SCHANNEL_BUFFER_FREE_SIZE   1024
 
diff --git a/m4/curl-openssl.m4 b/m4/curl-openssl.m4
index cd9074b02..5f5f87ae8 100644
--- a/m4/curl-openssl.m4
+++ b/m4/curl-openssl.m4
@@ -67,6 +67,7 @@ AC_DEFUN([CURL_CHECK_OPENSSL_API_HEADERS], [
     esac
     case $tst_api in
       0x110) tst_show="1.1.0" ;;
+      0x102) tst_show="1.0.2" ;;
       0x101) tst_show="1.0.1" ;;
       0x100) tst_show="1.0.0" ;;
       0x099) tst_show="0.9.9" ;;
@@ -140,6 +141,13 @@ AC_DEFUN([CURL_CHECK_OPENSSL_API_LIBRARY], [
   fi
   if test "$tst_api" = "unknown"; then
     AC_LINK_IFELSE([
+      AC_LANG_FUNC_LINK_TRY([SSL_CONF_CTX_new])
+    ],[
+      tst_api="0x102"
+    ])
+  fi
+  if test "$tst_api" = "unknown"; then
+    AC_LINK_IFELSE([
       AC_LANG_FUNC_LINK_TRY([SSL_renegotiate_abbreviated])
     ],[
       tst_api="0x101"
@@ -210,6 +218,7 @@ AC_DEFUN([CURL_CHECK_OPENSSL_API_LIBRARY], [
   fi
   case $tst_api in
     0x110) tst_show="1.1.0" ;;
+    0x102) tst_show="1.0.2" ;;
     0x101) tst_show="1.0.1" ;;
     0x100) tst_show="1.0.0" ;;
     0x099) tst_show="0.9.9" ;;
diff --git a/projects/README b/projects/README
index b45d78397..27095380a 100644
--- a/projects/README
+++ b/projects/README
@@ -110,6 +110,15 @@ Notes
    stored in the git repositoty) will need to be modified rather than the
    generated project files that Visual Studio uses.
 
+Legacy Windows and SSL
+======================
+Some of the project configurations use as an SSL backend WinSSL (Windows SSPI,
+more specifically Schannel), the native SSL library that comes with the Windows
+OS. WinSSL in Windows <= XP is not able to connect to servers that no longer
+support the legacy handshakes and algorithms used by those versions. If you
+will be using curl in one of those earlier versions of Windows you should
+choose another SSL backend like OpenSSL.
+
 TODO
 ====
 
diff --git a/src/tool_getparam.c b/src/tool_getparam.c
index c86e6b4b1..339fb7b5d 100644
--- a/src/tool_getparam.c
+++ b/src/tool_getparam.c
@@ -158,12 +158,10 @@ static const struct LongShort aliases[]= {
   {"$3", "keepalive-time",           TRUE},
   {"$4", "post302",                  FALSE},
   {"$5", "noproxy",                  TRUE},
-#if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI)
   {"$6", "socks5-gssapi-service",    TRUE},
   {"$7", "socks5-gssapi-nec",        FALSE},
   {"$O", "proxy-service-name",       TRUE},
   {"$P", "service-name",             TRUE},
-#endif
   {"$8", "proxy1.0",                 TRUE},
   {"$9", "tftp-blksize",             TRUE},
   {"$A", "mail-from",                TRUE},
@@ -898,7 +896,6 @@ ParameterError getparameter(char *flag,    /* f or -long-flag */
         /* This specifies the noproxy list */
         GetStr(&config->noproxy, nextarg);
         break;
-#if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI)
       case '6': /* --socks5-gssapi-service */
         GetStr(&config->socks5_gssapi_service, nextarg);
         break;
@@ -911,7 +908,6 @@ ParameterError getparameter(char *flag,    /* f or -long-flag */
       case 'P': /* --service-name */
         GetStr(&config->service_name, nextarg);
         break;
-#endif
       case '8': /* --proxy1.0 */
         /* http 1.0 proxy */
         GetStr(&config->proxy, nextarg);
diff --git a/src/tool_help.c b/src/tool_help.c
index 46ae341fe..59273036e 100644
--- a/src/tool_help.c
+++ b/src/tool_help.c
@@ -174,10 +174,8 @@ static const char *const helptext[] = {
   "     --proxy-negotiate  "
   "Use HTTP Negotiate (SPNEGO) authentication on the proxy (H)",
   "     --proxy-ntlm    Use NTLM authentication on the proxy (H)",
-#if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI)
   "     --proxy-service-name NAME  SPNEGO proxy service name",
   "     --service-name NAME  SPNEGO service name",
-#endif
   " -U, --proxy-user USER[:PASSWORD]  Proxy user and password",
   "     --proxy1.0 HOST[:PORT]  Use HTTP/1.0 proxy on given port",
   " -p, --proxytunnel   Operate through a HTTP proxy tunnel (using CONNECT)",
@@ -206,10 +204,8 @@ static const char *const helptext[] = {
   "     --socks5 HOST[:PORT]  SOCKS5 proxy on given host + port",
   "     --socks5-hostname HOST[:PORT]  "
   "SOCKS5 proxy, pass host name to proxy",
-#if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI)
   "     --socks5-gssapi-service NAME  SOCKS5 proxy service name for GSS-API",
   "     --socks5-gssapi-nec  Compatibility with NEC SOCKS5 server",
-#endif
   " -Y, --speed-limit RATE  "
   "Stop transfers below RATE for 'speed-time' secs",
   " -y, --speed-time SECONDS  "
@@ -224,7 +220,7 @@ static const char *const helptext[] = {
   " -t, --telnet-option OPT=VAL  Set telnet option",
   "     --tftp-blksize VALUE  Set TFTP BLKSIZE option (must be >512)",
   " -z, --time-cond TIME  Transfer based on a time condition",
-  " -1, --tlsv1         Use => TLSv1 (SSL)",
+  " -1, --tlsv1         Use >= TLSv1 (SSL)",
   "     --tlsv1.0       Use TLSv1.0 (SSL)",
   "     --tlsv1.1       Use TLSv1.1 (SSL)",
   "     --tlsv1.2       Use TLSv1.2 (SSL)",
diff --git a/src/tool_operate.c b/src/tool_operate.c
index fea587bc9..4c6ff854c 100644
--- a/src/tool_operate.c
+++ b/src/tool_operate.c
@@ -1204,32 +1204,26 @@ static CURLcode operate_do(struct GlobalConfig *global,
           my_setopt_enum(curl, CURLOPT_FTP_SSL_CCC,
                          (long)config->ftp_ssl_ccc_mode);
 
-#if defined(HAVE_GSSAPI) || defined(USE_WINDOWS_SSPI)
-        {
-          /* TODO: Make this a run-time check instead of compile-time one. */
-
-          /* new in curl 7.19.4 */
-          if(config->socks5_gssapi_service)
-            my_setopt_str(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE,
-                          config->socks5_gssapi_service);
-
-          /* new in curl 7.19.4 */
-          if(config->socks5_gssapi_nec)
-            my_setopt_str(curl, CURLOPT_SOCKS5_GSSAPI_NEC,
-                          config->socks5_gssapi_nec);
+        /* new in curl 7.19.4 */
+        if(config->socks5_gssapi_service)
+          my_setopt_str(curl, CURLOPT_SOCKS5_GSSAPI_SERVICE,
+                        config->socks5_gssapi_service);
+
+        /* new in curl 7.19.4 */
+        if(config->socks5_gssapi_nec)
+          my_setopt_str(curl, CURLOPT_SOCKS5_GSSAPI_NEC,
+                        config->socks5_gssapi_nec);
+
+        /* new in curl 7.43.0 */
+        if(config->proxy_service_name)
+          my_setopt_str(curl, CURLOPT_PROXY_SERVICE_NAME,
+                        config->proxy_service_name);
+
+        /* new in curl 7.43.0 */
+        if(config->service_name)
+          my_setopt_str(curl, CURLOPT_SERVICE_NAME,
+                        config->service_name);
 
-          /* new in curl 7.43.0 */
-          if(config->proxy_service_name)
-            my_setopt_str(curl, CURLOPT_PROXY_SERVICE_NAME,
-                          config->proxy_service_name);
-
-          /* new in curl 7.43.0 */
-          if(config->service_name)
-            my_setopt_str(curl, CURLOPT_SERVICE_NAME,
-                          config->service_name);
-
-        }
-#endif
         /* curl 7.13.0 */
         my_setopt_str(curl, CURLOPT_FTP_ACCOUNT, config->ftp_account);
 
diff --git a/tests/data/Makefile.inc b/tests/data/Makefile.inc
index 3e8ee4d6b..73877c678 100644
--- a/tests/data/Makefile.inc
+++ b/tests/data/Makefile.inc
@@ -165,4 +165,5 @@ test2000 test2001 test2002 test2003 test2004 test2005 test2006 test2007 \
 test2008 test2009 test2010 test2011 test2012 test2013 test2014 test2015 \
 test2016 test2017 test2018 test2019 test2020 test2021 test2022 test2023 \
 test2024 test2025 test2026 test2027 test2028 test2029 test2030 test2031 \
-test2032 test2033 test2034 test2035 test2036 test2037 test2038 test2039
+test2032 test2033 test2034 test2035 test2036 test2037 test2038 test2039 \
+test2040
diff --git a/tests/data/test1530 b/tests/data/test1530
index 92abc6ce4..8372d29ef 100644
--- a/tests/data/test1530
+++ b/tests/data/test1530
@@ -9,6 +9,9 @@ CURLOPT_OPENSOCKETFUNCTION
 <server>
 none
 </server>
+<features>
+http
+</features>
 <tool>
 lib1530
 </tool>
diff --git a/tests/data/test2040 b/tests/data/test2040
new file mode 100644
index 000000000..ac600174e
--- /dev/null
+++ b/tests/data/test2040
@@ -0,0 +1,69 @@
+<testcase>
+<info>
+<keywords>
+HTTP
+HTTP GET
+HTTP Basic auth
+</keywords>
+</info>
+# Server-side
+<reply>
+
+<!-- First request has Basic auth, right password -->
+<data100>
+HTTP/1.1 200 Things are fine in server land
+Server: Microsoft-IIS/5.0
+Content-Type: text/html; charset=iso-8859-1
+Content-Length: 32
+
+Finally, this is the real page!
+</data100>
+
+<!-- Second request with Basic auth disabled -->
+<data200>
+HTTP/1.1 401 Sorry wrong password (2)
+Server: Microsoft-IIS/5.0
+Content-Type: text/html; charset=iso-8859-1
+Content-Length: 29
+WWW-Authenticate: Basic realm="testrealm"
+
+This is a bad password page!
+</data200>
+
+</reply>
+
+# Client-side
+<client>
+<server>
+http
+</server>
+<name>
+HTTP Basic authorization, then without authorization
+</name>
+<command option="no-output,no-include">
+-u testuser:testpass http://%HOSTIP:%HTTPPORT/20400100 --next --no-basic http://%HOSTIP:%HTTPPORT/20400200
+</command>
+</client>
+
+# Verify data after the test has been "shot"
+<verify>
+<strip>
+^User-Agent:.*
+</strip>
+<protocol>
+GET /20400100 HTTP/1.1

+Host: %HOSTIP:%HTTPPORT

+Authorization: Basic dGVzdHVzZXI6dGVzdHBhc3M=

+Accept: */*

+

+GET /20400200 HTTP/1.1

+Host: %HOSTIP:%HTTPPORT

+Accept: */*

+

+</protocol>
+<stdout>
+Finally, this is the real page!
+This is a bad password page!
+</stdout>
+</verify>
+</testcase>
diff --git a/winbuild/BUILD.WINDOWS.txt b/winbuild/BUILD.WINDOWS.txt
index 600f73746..ed19e56c0 100644
--- a/winbuild/BUILD.WINDOWS.txt
+++ b/winbuild/BUILD.WINDOWS.txt
@@ -1,5 +1,5 @@
-Building with Visual C++, prerequises

-=====================================

+Building with Visual C++, prerequisites

+=======================================

 

    This document describes how to compile, build and install curl and libcurl

    from sources using the Visual C++ build tool. To build with VC++, you will

@@ -87,3 +87,12 @@ therefore rarely tested. When passing RTLIBCFG for a configuration that was
 already built but not with that option, or if the option was specified

 differently, you must destroy the build directory containing the configuration

 so that nmake can build it from scratch.

+

+Legacy Windows and SSL

+======================

+When you build curl using the build files in this directory the default SSL

+backend will be WinSSL (Windows SSPI, more specifically Schannel), the native

+SSL library that comes with the Windows OS. WinSSL in Windows <= XP is not able

+to connect to servers that no longer support the legacy handshakes and

+algorithms used by those versions. If you will be using curl in one of those

+earlier versions of Windows you should choose another SSL backend like OpenSSL.