THANKS: 18 new contributors for 7.37.0

Possibly the final update before release...

.gitignore

@@ -45,3 +45,5 @@ CHANGES.dist
 .project
 .cproject
 .settings
+/[0-9]*.patch
+.dirstamp

.travis.yml

@@ -0,0 +1,11 @@
+language: c
+
+before_script:
+  - ./buildconf
+
+compiler:
+  - clang
+  - gcc
+
+notifications:
+  email: false

CMake/Platforms/WindowsCache.cmake

@@ -108,7 +108,11 @@ if(NOT UNIX)
     set(HAVE_IN_ADDR_T 0)
     set(HAVE_INET_NTOA_R_DECL 0)
     set(HAVE_INET_NTOA_R_DECL_REENTRANT 0)
-    set(HAVE_GETADDRINFO 0)
+    if(ENABLE_IPV6)
+      set(HAVE_GETADDRINFO 1)
+    else()
+      set(HAVE_GETADDRINFO 0)
+    endif()
     set(STDC_HEADERS 1)
     set(RETSIGTYPE_TEST 1)
 

CMakeLists.txt

@@ -1,3 +1,24 @@
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 1998 - 2014, 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
+# are also available at http://curl.haxx.se/docs/copyright.html.
+#
+# You may opt to use, copy, modify, merge, publish, distribute and/or sell
+# copies of the Software, and permit persons to whom the Software is
+# furnished to do so, under the terms of the COPYING file.
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+# KIND, either express or implied.
+#
+###########################################################################
 # cURL/libcurl CMake script
 # by Tetetest and Sukender (Benoit Neil)
 
@@ -23,6 +44,8 @@ include(Utilities)
 
 project( CURL C )
 
+message(WARNING "the curl cmake build system is poorly maintained. Be aware")
+
 file (READ ${CURL_SOURCE_DIR}/include/curl/curlver.h CURL_VERSION_H_CONTENTS)
 string (REGEX MATCH "LIBCURL_VERSION_MAJOR[ \t]+([0-9]+)"
   LIBCURL_VERSION_MJ ${CURL_VERSION_H_CONTENTS})
@@ -783,6 +806,17 @@ else()
   set(CURL_SIZEOF_CURL_SOCKLEN_T ${SIZEOF_INT})
 endif()
 
+# TODO test which of these headers are required for the typedefs used in curlbuild.h
+if(WIN32)
+  set(CURL_PULL_WS2TCPIP_H ${HAVE_WS2TCPIP_H})
+else()
+  set(CURL_PULL_SYS_TYPES_H ${HAVE_SYS_TYPES_H})
+  set(CURL_PULL_SYS_SOCKET_H ${HAVE_SYS_SOCKET_H})
+  set(CURL_PULL_SYS_POLL_H ${HAVE_SYS_POLL_H})
+endif()
+set(CURL_PULL_STDINT_H ${HAVE_STDINT_H})
+set(CURL_PULL_INTTYPES_H ${HAVE_INTTYPES_H})
+
 include(CMake/OtherTests.cmake)
 
 add_definitions(-DHAVE_CONFIG_H)

COPYING

@@ -1,6 +1,6 @@
 COPYRIGHT AND PERMISSION NOTICE
 
-Copyright (c) 1996 - 2013, Daniel Stenberg, <daniel@haxx.se>.
+Copyright (c) 1996 - 2014, Daniel Stenberg, <daniel@haxx.se>.
 
 All rights reserved.
 

MacOSX-Framework

@@ -10,6 +10,10 @@
 # 10.5 is the *ONLY* SDK that support PPC64 :( -- 10.6 do not have ppc64 support
 #If you need to have PPC64 support then change below to 1
 PPC64_NEEDED=0
+# Apple does not support building for PPC anymore in Xcode 4 and later.
+# If you're using Xcode 3 or earlier and need PPC support, then change
+# the setting below to 1
+PPC_NEEDED=0
 
 # For me the default is to develop for the platform I am on, and if you
 #desire compatibility with older versions then change USE_OLD to 1 :)
@@ -24,9 +28,16 @@ FRAMEWORK_VERSION=Versions/Release-$VERSION
 # and setup the right paths to this version, leaving the system version
 # "intact", so you can "fix" it later with the links to Versions/A/...
 
-
+DEVELOPER_PATH=`xcode-select --print-path`
-OLD_SDK=`ls  /Developer/SDKs|head -1`
+# Around Xcode 4.3, SDKs were moved from the Developer folder into the
-NEW_SDK=`ls -r /Developer/SDKs|head -1`
+# MacOSX.platform folder
+if test -d "$DEVELOPER_PATH/Platforms/MacOSX.platform/Developer/SDKs"; then
+ SDK_PATH="$DEVELOPER_PATH/Platforms/MacOSX.platform/Developer/SDKs"
+else
+ SDK_PATH="$DEVELOPER_PATH/SDKs";
+fi
+OLD_SDK=`ls  $SDK_PATH|head -1`
+NEW_SDK=`ls -r $SDK_PATH|head -1`
 
 if test "0"$USE_OLD -gt 0
 then
@@ -37,21 +48,24 @@ fi
 
 MACVER=`echo $SDK32|sed -e s/[a-zA-Z]//g -e s/.\$//`
 
-SDK32_DIR='/Developer/SDKs/'$SDK32
+SDK32_DIR=$SDK_PATH/$SDK32
 MINVER32='-mmacosx-version-min='$MACVER
-ARCHES32='-arch i386 -arch ppc'
+if test $PPC_NEEDED -gt 0; then
-
+ ARCHES32='-arch i386 -arch ppc'
+else
+ ARCHES32='-arch i386'
+fi
 
 if test $PPC64_NEEDED -gt 0
 then
   SDK64=10.5
   ARCHES64='-arch x86_64 -arch ppc64'
-  SDK64=`ls  /Developer/SDKs|grep 10.5|head -1`
+  SDK64=`ls  $SDK_PATH|grep 10.5|head -1`
 else
  ARCHES64='-arch x86_64'
  #We "know" that 10.4 and earlier do not support 64bit
- OLD_SDK64=`ls  /Developer/SDKs|egrep -v "10.[0-4]"|head -1`
+ OLD_SDK64=`ls  $SDK_PATH|egrep -v "10.[0-4]"|head -1`
- NEW_SDK64=`ls -r /Developer/SDKs|egrep -v "10.[0-4]"|head -1`
+ NEW_SDK64=`ls -r $SDK_PATH|egrep -v "10.[0-4]"|head -1`
  if test $USE_OLD -gt 0
   then
    SDK64=$OLD_SDK64
@@ -60,7 +74,7 @@ else
   fi
 fi
 
-SDK64_DIR='/Developer/SDKs/'$SDK64
+SDK64_DIR=$SDK_PATH/$SDK64
 MACVER64=`echo $SDK64|sed -e s/[a-zA-Z]//g -e s/.\$//`
 
 MINVER64='-mmacosx-version-min='$MACVER64
@@ -68,13 +82,13 @@ MINVER64='-mmacosx-version-min='$MACVER64
 if test ! -z $SDK32; then
   echo "----Configuring libcurl for 32 bit universal framework..."
   make clean
-  ./configure --disable-dependency-tracking --disable-static --with-gssapi \
+  ./configure --disable-dependency-tracking --disable-static --with-gssapi --with-darwinssl \
-    CFLAGS="-Os -isysroot $SDK32_DIR $ARCHES32 $MINVER32" \
+    CFLAGS="-Os -isysroot $SDK32_DIR $ARCHES32" \
-    LDFLAGS="-Wl,-syslibroot,$SDK32_DIR $ARCHES32 $MINVER32 -Wl,-headerpad_max_install_names" \
+    LDFLAGS="-Wl,-syslibroot,$SDK32_DIR $ARCHES32 -Wl,-headerpad_max_install_names" \
     CC=$CC
 
   echo "----Building 32 bit libcurl..."
-  make
+  make -j `sysctl -n hw.logicalcpu_max`
 
   echo "----Creating 32 bit framework..."
   rm -r libcurl.framework
@@ -89,21 +103,21 @@ if test ! -z $SDK32; then
   ln -fs ${FRAMEWORK_VERSION}/Resources Resources
   ln -fs ${FRAMEWORK_VERSION}/Headers Headers
   cd Versions
-  ln -fs ${FRAMEWORK_VERSION} Current
+  ln -fs $(basename "${FRAMEWORK_VERSION}") Current
 
-  echo TEsting for SDK64
+  echo Testing for SDK64
   if test -d $SDK64_DIR; then
   echo entering...
     popd
     make clean
     echo "----Configuring libcurl for 64 bit universal framework..."
-    ./configure --disable-dependency-tracking --disable-static --with-gssapi \
+    ./configure --disable-dependency-tracking --disable-static --with-gssapi --with-darwinssl \
-      CFLAGS="-Os -isysroot $SDK64_DIR $ARCHES64 $MINVER64" \
+      CFLAGS="-Os -isysroot $SDK64_DIR $ARCHES64" \
-      LDFLAGS="-Wl,-syslibroot,$SDK64_DIR $ARCHES64 $MINVER64 -Wl,-headerpad_max_install_names" \
+      LDFLAGS="-Wl,-syslibroot,$SDK64_DIR $ARCHES64 -Wl,-headerpad_max_install_names" \
       CC=$CC
 
     echo "----Building 64 bit libcurl..."
-    make
+    make -j `sysctl -n hw.logicalcpu_max`
 
     echo "----Appending 64 bit framework to 32 bit framework..."
     cp lib/.libs/libcurl.dylib libcurl.framework/${FRAMEWORK_VERSION}/libcurl64

Makefile.am

@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
 #
 # This software is licensed as described in the file COPYING, which
 # you should have received as part of this distribution. The terms
@@ -30,13 +30,101 @@ CMake/CurlTests.c CMake/FindOpenSSL.cmake CMake/FindZLIB.cmake		\
 CMake/OtherTests.cmake CMake/Platforms/WindowsCache.cmake		\
 CMake/Utilities.cmake include/curl/curlbuild.h.cmake
 
+VC6_LIBTMPL = projects/Windows/VC6/lib/libcurl.tmpl
+VC6_LIBDSP = projects/Windows/VC6/lib/libcurl.dsp
+VC6_LIBDSP_DEPS = $(VC6_LIBTMPL) Makefile.am lib/Makefile.inc
+VC6_SRCTMPL = projects/Windows/VC6/src/curlsrc.tmpl
+VC6_SRCDSP = projects/Windows/VC6/src/curlsrc.dsp
+VC6_SRCDSP_DEPS = $(VC6_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC7_LIBTMPL = projects/Windows/VC7/lib/libcurl.tmpl
+VC7_LIBVCPROJ = projects/Windows/VC7/lib/libcurl.vcproj
+VC7_LIBVCPROJ_DEPS = $(VC7_LIBTMPL) Makefile.am lib/Makefile.inc
+VC7_SRCTMPL = projects/Windows/VC7/src/curlsrc.tmpl
+VC7_SRCVCPROJ = projects/Windows/VC7/src/curlsrc.vcproj
+VC7_SRCVCPROJ_DEPS = $(VC7_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC71_LIBTMPL = projects/Windows/VC7.1/lib/libcurl.tmpl
+VC71_LIBVCPROJ = projects/Windows/VC7.1/lib/libcurl.vcproj
+VC71_LIBVCPROJ_DEPS = $(VC71_LIBTMPL) Makefile.am lib/Makefile.inc
+VC71_SRCTMPL = projects/Windows/VC7.1/src/curlsrc.tmpl
+VC71_SRCVCPROJ = projects/Windows/VC7.1/src/curlsrc.vcproj
+VC71_SRCVCPROJ_DEPS = $(VC71_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC8_LIBTMPL = projects/Windows/VC8/lib/libcurl.tmpl
+VC8_LIBVCPROJ = projects/Windows/VC8/lib/libcurl.vcproj
+VC8_LIBVCPROJ_DEPS = $(VC8_LIBTMPL) Makefile.am lib/Makefile.inc
+VC8_SRCTMPL = projects/Windows/VC8/src/curlsrc.tmpl
+VC8_SRCVCPROJ = projects/Windows/VC8/src/curlsrc.vcproj
+VC8_SRCVCPROJ_DEPS = $(VC8_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC9_LIBTMPL = projects/Windows/VC9/lib/libcurl.tmpl
+VC9_LIBVCPROJ = projects/Windows/VC9/lib/libcurl.vcproj
+VC9_LIBVCPROJ_DEPS = $(VC9_LIBTMPL) Makefile.am lib/Makefile.inc
+VC9_SRCTMPL = projects/Windows/VC9/src/curlsrc.tmpl
+VC9_SRCVCPROJ = projects/Windows/VC9/src/curlsrc.vcproj
+VC9_SRCVCPROJ_DEPS = $(VC9_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC10_LIBTMPL = projects/Windows/VC10/lib/libcurl.tmpl
+VC10_LIBVCXPROJ = projects/Windows/VC10/lib/libcurl.vcxproj
+VC10_LIBVCXPROJ_DEPS = $(VC10_LIBTMPL) Makefile.am lib/Makefile.inc
+VC10_SRCTMPL = projects/Windows/VC10/src/curlsrc.tmpl
+VC10_SRCVCXPROJ = projects/Windows/VC10/src/curlsrc.vcxproj
+VC10_SRCVCXPROJ_DEPS = $(VC10_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC11_LIBTMPL = projects/Windows/VC11/lib/libcurl.tmpl
+VC11_LIBVCXPROJ = projects/Windows/VC11/lib/libcurl.vcxproj
+VC11_LIBVCXPROJ_DEPS = $(VC11_LIBTMPL) Makefile.am lib/Makefile.inc
+VC11_SRCTMPL = projects/Windows/VC11/src/curlsrc.tmpl
+VC11_SRCVCXPROJ = projects/Windows/VC11/src/curlsrc.vcxproj
+VC11_SRCVCXPROJ_DEPS = $(VC11_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC12_LIBTMPL = projects/Windows/VC12/lib/libcurl.tmpl
+VC12_LIBVCXPROJ = projects/Windows/VC12/lib/libcurl.vcxproj
+VC12_LIBVCXPROJ_DEPS = $(VC12_LIBTMPL) Makefile.am lib/Makefile.inc
+VC12_SRCTMPL = projects/Windows/VC12/src/curlsrc.tmpl
+VC12_SRCVCXPROJ = projects/Windows/VC12/src/curlsrc.vcxproj
+VC12_SRCVCXPROJ_DEPS = $(VC12_SRCTMPL) Makefile.am src/Makefile.inc
+
+VC_DIST = projects/README	\
+ projects/build-openssl.bat	\
+ projects/Windows/VC6/curl.dsw	\
+ projects/Windows/VC6/lib/libcurl.dsw $(VC6_LIBDSP)	\
+ projects/Windows/VC6/src/curlsrc.dsw $(VC6_SRCDSP)	\
+ projects/Windows/VC7/curl.sln	\
+ projects/Windows/VC7/lib/libcurl.sln $(VC7_LIBVCPROJ)	\
+ projects/Windows/VC7/src/curlsrc.sln $(VC7_SRCVCPROJ)	\
+ projects/Windows/VC7.1/curl.sln	\
+ projects/Windows/VC7.1/lib/libcurl.sln $(VC71_LIBVCPROJ)	\
+ projects/Windows/VC7.1/src/curlsrc.sln $(VC71_SRCVCPROJ)	\
+ projects/Windows/VC8/curl.sln	\
+ projects/Windows/VC8/lib/libcurl.sln $(VC8_LIBVCPROJ)	\
+ projects/Windows/VC8/src/curlsrc.sln $(VC8_SRCVCPROJ)	\
+ projects/Windows/VC9/curl.sln	\
+ projects/Windows/VC9/lib/libcurl.sln $(VC9_LIBVCPROJ)	\
+ projects/Windows/VC9/src/curlsrc.sln $(VC9_SRCVCPROJ)	\
+ projects/Windows/VC10/curl.sln	\
+ projects/Windows/VC10/lib/libcurl.sln $(VC10_LIBVCXPROJ)	\
+ projects/Windows/VC10/src/curlsrc.sln $(VC10_SRCVCXPROJ)	\
+ projects/Windows/VC11/curl.sln	\
+ projects/Windows/VC11/lib/libcurl.sln $(VC11_LIBVCXPROJ)	\
+ projects/Windows/VC11/src/curlsrc.sln $(VC11_SRCVCXPROJ)	\
+ projects/Windows/VC12/curl.sln	\
+ projects/Windows/VC12/lib/libcurl.sln $(VC12_LIBVCXPROJ)	\
+ projects/Windows/VC12/src/curlsrc.sln $(VC12_SRCVCXPROJ)
+
 WINBUILD_DIST = winbuild/BUILD.WINDOWS.txt winbuild/gen_resp_file.bat	\
-winbuild/MakefileBuild.vc winbuild/Makefile.vc
+ winbuild/MakefileBuild.vc winbuild/Makefile.vc				\
+ winbuild/Makefile.msvc.names
 
 EXTRA_DIST = CHANGES COPYING maketgz Makefile.dist curl-config.in	\
- curl-style.el sample.emacs RELEASE-NOTES buildconf 	\
+ RELEASE-NOTES buildconf libcurl.pc.in MacOSX-Framework	\
- libcurl.pc.in vc6curl.dsw MacOSX-Framework Android.mk $(CMAKE_DIST)	\
+ $(CMAKE_DIST) $(VC_DIST) $(WINBUILD_DIST) lib/libcurl.vers.in
- Makefile.msvc.names $(WINBUILD_DIST) lib/libcurl.vers.in
+
+CLEANFILES = $(VC6_LIBDSP) $(VC6_SRCDSP) $(VC7_LIBVCPROJ) $(VC7_SRCVCPROJ)	\
+ $(VC71_LIBVCPROJ) $(VC71_SRCVCPROJ) $(VC8_LIBVCPROJ) $(VC8_SRCVCPROJ)	\
+ $(VC9_LIBVCPROJ) $(VC9_SRCVCPROJ) $(VC10_LIBVCXPROJ) $(VC10_SRCVCXPROJ)	\
+ $(VC11_LIBVCXPROJ) $(VC11_SRCVCXPROJ) $(VC12_LIBVCXPROJ) $(VC12_SRCVCXPROJ)
 
 bin_SCRIPTS = curl-config
 
@@ -46,6 +134,10 @@ DIST_SUBDIRS = $(SUBDIRS) tests packages docs
 pkgconfigdir = $(libdir)/pkgconfig
 pkgconfig_DATA = libcurl.pc
 
+# List of files required to generate VC IDE .dsp, .vcproj and .vcxproj files
+include lib/Makefile.inc
+include src/Makefile.inc
+
 dist-hook:
 	rm -rf $(top_builddir)/tests/log
 	find $(distdir) -name "*.dist" -exec rm {} \;
@@ -89,7 +181,7 @@ endif
 examples:
 	@(cd docs/examples; $(MAKE) check)
 
-# This is a hook to have 'make clean' also clean up the dosc and the tests
+# This is a hook to have 'make clean' also clean up the docs and the tests
 # dir. The extra check for the Makefiles being present is necessary because
 # 'make distcheck' will make clean first in these directories _before_ it runs
 # this hook.
@@ -156,13 +248,249 @@ uninstall-hook:
 	cd docs && $(MAKE) uninstall
 
 ca-bundle: lib/mk-ca-bundle.pl
-	@echo "generate a fresh ca-bundle.crt"
+	@echo "generating a fresh ca-bundle.crt"
 	@perl $< -b -l -u lib/ca-bundle.crt
 
 ca-firefox: lib/firefox-db2pem.sh
-	@echo "generate a fresh ca-bundle.crt"
+	@echo "generating a fresh ca-bundle.crt"
 	./lib/firefox-db2pem.sh lib/ca-bundle.crt
 
 checksrc:
 	cd lib && $(MAKE) checksrc
 	cd src && $(MAKE) checksrc
+
+.PHONY: vc-ide
+
+vc-ide: $(VC6_LIBDSP_DEPS) $(VC6_SRCDSP_DEPS) $(VC7_LIBVCPROJ_DEPS)	\
+ $(VC7_SRCVCPROJ_DEPS) $(VC71_LIBVCPROJ_DEPS) $(VC71_SRCVCPROJ_DEPS)	\
+ $(VC8_LIBVCPROJ_DEPS) $(VC8_SRCVCPROJ_DEPS) $(VC9_LIBVCPROJ_DEPS)	\
+ $(VC9_SRCVCPROJ_DEPS) $(VC10_LIBVCXPROJ_DEPS) $(VC10_SRCVCXPROJ_DEPS)	\
+ $(VC11_LIBVCXPROJ_DEPS) $(VC11_SRCVCXPROJ_DEPS) $(VC12_LIBVCXPROJ_DEPS)	\
+ $(VC12_SRCVCXPROJ_DEPS)
+	@(win32_lib_srcs='$(LIB_CFILES)'; \
+	win32_lib_hdrs='$(LIB_HFILES) config-win32.h'; \
+	win32_lib_rc='$(LIB_RCFILES)'; \
+	win32_lib_vtls_srcs='$(LIB_VTLS_CFILES)'; \
+	win32_lib_vtls_hdrs='$(LIB_VTLS_HFILES)'; \
+	win32_src_srcs='$(CURL_CFILES)'; \
+	win32_src_hdrs='$(CURL_HFILES)'; \
+	win32_src_rc='$(CURL_RCFILES)'; \
+	\
+	sorted_lib_srcs=`for file in $$win32_lib_srcs; do echo $$file; done | sort`; \
+	sorted_lib_hdrs=`for file in $$win32_lib_hdrs; do echo $$file; done | sort`; \
+	sorted_lib_vtls_srcs=`for file in $$win32_lib_vtls_srcs; do echo $$file; done | sort`; \
+	sorted_lib_vtls_hdrs=`for file in $$win32_lib_vtls_hdrs; do echo $$file; done | sort`; \
+	sorted_src_srcs=`for file in $$win32_src_srcs; do echo $$file; done | sort`; \
+	sorted_src_hdrs=`for file in $$win32_src_hdrs; do echo $$file; done | sort`; \
+	\
+	awk_code='\
+function gen_element(type, dir, file)\
+{\
+  sub(/vtls\//, "", file);\
+\
+  spaces="    ";\
+  if(dir == "lib\\vtls")\
+    tabs="				";\
+  else\
+    tabs="			";\
+\
+  if(type == "dsp") {\
+    printf("# Begin Source File\r\n");\
+    printf("\r\n");\
+    printf("SOURCE=..\\..\\..\\..\\%s\\%s\r\n", dir, file);\
+    printf("# End Source File\r\n");\
+  }\
+  else if(type == "vcproj1") {\
+    printf("%s<File\r\n", tabs);\
+    printf("%s	RelativePath=\"..\\..\\..\\..\\%s\\%s\">\r\n",\
+           tabs, dir, file);\
+    printf("%s</File>\r\n", tabs);\
+  }\
+  else if(type == "vcproj2") {\
+    printf("%s<File\r\n", tabs);\
+    printf("%s	RelativePath=\"..\\..\\..\\..\\%s\\%s\"\r\n",\
+           tabs, dir, file);\
+    printf("%s>\r\n", tabs);\
+    printf("%s</File>\r\n", tabs);\
+  }\
+  else if(type == "vcxproj") {\
+    i = index(file, ".");\
+    ext = substr(file, i == 0 ? 0 : i + 1);\
+\
+    if(ext == "c")\
+      printf("%s<ClCompile Include=\"..\\..\\..\\..\\%s\\%s\" />\r\n",\
+             spaces, dir, file);\
+    else if(ext == "h")\
+      printf("%s<ClInclude Include=\"..\\..\\..\\..\\%s\\%s\" />\r\n",\
+             spaces, dir, file);\
+    else if(ext == "rc")\
+      printf("%s<ResourceCompile Include=\"..\\..\\..\\..\\%s\\%s\" />\r\n",\
+      spaces, dir, file);\
+  }\
+}\
+\
+{\
+\
+  if($$0 == "CURL_LIB_C_FILES") {\
+    split(lib_srcs, arr);\
+    for(val in arr) gen_element(proj_type, "lib", arr[val]);\
+  }\
+  else if($$0 == "CURL_LIB_H_FILES") {\
+    split(lib_hdrs, arr);\
+    for(val in arr) gen_element(proj_type, "lib", arr[val]);\
+  }\
+  else if($$0 == "CURL_LIB_RC_FILES") {\
+    split(lib_rc, arr);\
+    for(val in arr) gen_element(proj_type, "lib", arr[val]);\
+  }\
+  else if($$0 == "CURL_LIB_VTLS_C_FILES") {\
+    split(lib_vtls_srcs, arr);\
+    for(val in arr) gen_element(proj_type, "lib\\vtls", arr[val]);\
+  }\
+  else if($$0 == "CURL_LIB_VTLS_H_FILES") {\
+    split(lib_vtls_hdrs, arr);\
+    for(val in arr) gen_element(proj_type, "lib\\vtls", arr[val]);\
+  }\
+  else if($$0 == "CURL_SRC_C_FILES") {\
+    split(src_srcs, arr);\
+    for(val in arr) gen_element(proj_type, "src", arr[val]);\
+  }\
+  else if($$0 == "CURL_SRC_H_FILES") {\
+    split(src_hdrs, arr);\
+    for(val in arr) gen_element(proj_type, "src", arr[val]);\
+  }\
+  else if($$0 == "CURL_SRC_RC_FILES") {\
+    split(src_rc, arr);\
+    for(val in arr) gen_element(proj_type, "src", arr[val]);\
+  }\
+  else\
+    printf("%s\r\n", $$0);\
+}';\
+	\
+	echo "generating '$(VC6_LIBDSP)'"; \
+	awk -v proj_type=dsp \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC6_LIBTMPL) > $(VC6_LIBDSP) || { exit 1; }; \
+	\
+	echo "generating '$(VC6_SRCDSP)'"; \
+	awk -v proj_type=dsp \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC6_SRCTMPL) > $(VC6_SRCDSP) || { exit 1; }; \
+	\
+	echo "generating '$(VC7_LIBVCPROJ)'"; \
+	awk -v proj_type=vcproj1 \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC7_LIBTMPL) > $(VC7_LIBVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC7_SRCVCPROJ)'"; \
+	awk -v proj_type=vcproj1 \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC7_SRCTMPL) > $(VC7_SRCVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC71_LIBVCPROJ)'"; \
+	awk -v proj_type=vcproj1 \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC71_LIBTMPL) > $(VC71_LIBVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC71_SRCVCPROJ)'"; \
+	awk -v proj_type=vcproj1 \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC71_SRCTMPL) > $(VC71_SRCVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC8_LIBVCPROJ)'"; \
+	awk -v proj_type=vcproj2 \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC8_LIBTMPL) > $(VC8_LIBVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC8_SRCVCPROJ)'"; \
+	awk -v proj_type=vcproj2 \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC8_SRCTMPL) > $(VC8_SRCVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC9_LIBVCPROJ)'"; \
+	awk -v proj_type=vcproj2 \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC9_LIBTMPL) > $(VC9_LIBVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC9_SRCVCPROJ)'"; \
+	awk -v proj_type=vcproj2 \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC9_SRCTMPL) > $(VC9_SRCVCPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC10_LIBVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC10_LIBTMPL) > $(VC10_LIBVCXPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC10_SRCVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC10_SRCTMPL) > $(VC10_SRCVCXPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC11_LIBVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC11_LIBTMPL) > $(VC11_LIBVCXPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC11_SRCVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC11_SRCTMPL) > $(VC11_SRCVCXPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC12_LIBVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v lib_srcs="$$sorted_lib_srcs" \
+		-v lib_hdrs="$$sorted_lib_hdrs" \
+		-v lib_rc="$$win32_lib_rc" \
+		-v lib_vtls_srcs="$$sorted_lib_vtls_srcs" \
+		-v lib_vtls_hdrs="$$sorted_lib_vtls_hdrs" \
+		"$$awk_code" $(srcdir)/$(VC12_LIBTMPL) > $(VC12_LIBVCXPROJ) || { exit 1; }; \
+	\
+	echo "generating '$(VC12_SRCVCXPROJ)'"; \
+	awk -v proj_type=vcxproj \
+		-v src_srcs="$$sorted_src_srcs" \
+		-v src_hdrs="$$sorted_src_hdrs" \
+		-v src_rc="$$win32_src_rc" \
+		"$$awk_code" $(srcdir)/$(VC12_SRCTMPL) > $(VC12_SRCVCXPROJ) || { exit 1; };)

Makefile.dist

@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 1998 - 2010, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 1998 - 2014, 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
@@ -136,24 +136,60 @@ vc-zlib: $(VC)
 	cd ..\src
 	nmake /f Makefile.$(VC) cfg=release-zlib
 
+vc-x64-zlib: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-zlib
+	cd ..\src
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-zlib
+
 vc-ssl: $(VC)
 	cd lib
 	nmake /f Makefile.$(VC) cfg=release-ssl
 	cd ..\src
 	nmake /f Makefile.$(VC) cfg=release-ssl
 
+vc-winssl: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) cfg=release-winssl WINDOWS_SSPI=1
+	cd ..\src
+	nmake /f Makefile.$(VC) cfg=release-winssl WINDOWS_SSPI=1
+
+vc-x64-ssl: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-ssl
+	cd ..\src
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-ssl
+
+vc-x64-winssl: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-winssl WINDOWS_SSPI=1
+	cd ..\src
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-winssl WINDOWS_SSPI=1
+
 vc-ssl-zlib: $(VC)
 	cd lib
 	nmake /f Makefile.$(VC) cfg=release-ssl-zlib
 	cd ..\src
 	nmake /f Makefile.$(VC) cfg=release-ssl-zlib
 
+vc-winssl-zlib: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) cfg=release-winssl-zlib
+	cd ..\src
+	nmake /f Makefile.$(VC) cfg=release-winssl-zlib
+
 vc-x64-ssl-zlib: $(VC)
 	cd lib
 	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-ssl-zlib
 	cd ..\src
 	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-ssl-zlib
 
+vc-x64-winssl-zlib: $(VC)
+	cd lib
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-winssl-zlib
+	cd ..\src
+	nmake /f Makefile.$(VC) MACHINE=x64 cfg=release-winssl-zlib
+
 vc-ssl-dll: $(VC)
 	cd lib
 	nmake /f Makefile.$(VC) cfg=release-ssl-dll
@@ -254,6 +290,18 @@ linux-ssl: ssl
 # We don't need to do anything for vc6.
 vc6:
 
+# VC7 makefiles are for use with VS.NET and VS.NET 2003
+vc7: lib/Makefile.vc7 src/Makefile.vc7
+
+lib/Makefile.vc7: lib/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s/VC6/VC7/g" lib/Makefile.vc6 > lib/Makefile.vc7
+
+src/Makefile.vc7: src/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s/VC6/VC7/g" src/Makefile.vc6 > src/Makefile.vc7
+
+# VC8 makefiles are for use with VS2005
 vc8: lib/Makefile.vc8 src/Makefile.vc8
 
 lib/Makefile.vc8: lib/Makefile.vc6
@@ -286,6 +334,28 @@ src/Makefile.vc10: src/Makefile.vc6
 	@echo "generate $@"
 	@sed -e "s#/GX /DWIN32 /YX#/EHsc /DWIN32#" -e "s#/GZ#/RTC1#" -e "s/ws2_32.lib/ws2_32.lib/g" -e "s/vc6/vc10/g" -e "s/VC6/VC10/g" src/Makefile.vc6 > src/Makefile.vc10
 
+# VC11 makefiles are for use with VS2012
+vc11: lib/Makefile.vc11 src/Makefile.vc11
+
+lib/Makefile.vc11: lib/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s#/GX /DWIN32 /YX#/EHsc /DWIN32#" -e "s#/GZ#/RTC1#" -e "s/ws2_32.lib/ws2_32.lib/g" -e "s/vc6/vc11/g" -e "s/VC6/VC11/g" lib/Makefile.vc6 > lib/Makefile.vc11
+
+src/Makefile.vc11: src/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s#/GX /DWIN32 /YX#/EHsc /DWIN32#" -e "s#/GZ#/RTC1#" -e "s/ws2_32.lib/ws2_32.lib/g" -e "s/vc6/vc11/g" -e "s/VC6/VC11/g" src/Makefile.vc6 > src/Makefile.vc11
+
+# VC12 makefiles are for use with VS2013
+vc12: lib/Makefile.vc12 src/Makefile.vc12
+
+lib/Makefile.vc12: lib/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s#/GX /DWIN32 /YX#/EHsc /DWIN32#" -e "s#/GZ#/RTC1#" -e "s/ws2_32.lib/ws2_32.lib/g" -e "s/vc6/vc12/g" -e "s/VC6/VC12/g" lib/Makefile.vc6 > lib/Makefile.vc12
+
+src/Makefile.vc12: src/Makefile.vc6
+	@echo "generate $@"
+	@sed -e "s#/GX /DWIN32 /YX#/EHsc /DWIN32#" -e "s#/GZ#/RTC1#" -e "s/ws2_32.lib/ws2_32.lib/g" -e "s/vc6/vc12/g" -e "s/VC6/VC12/g" src/Makefile.vc6 > src/Makefile.vc12
+
 ca-bundle: lib/mk-ca-bundle.pl
 	@echo "generate a fresh ca-bundle.crt"
 	@perl $< -b -l -u lib/ca-bundle.crt

RELEASE-NOTES

@@ -1,66 +1,87 @@
-Curl and libcurl 7.29.0
+Curl and libcurl 7.37.0
 
- Public curl releases:         131
+ Public curl releases:         139
- Command line options:         152
+ Command line options:         161
- curl_easy_setopt() options:   199
+ curl_easy_setopt() options:   206
  Public functions in libcurl:  58
- Known libcurl bindings:       39
+ Contributors:                 1137
- Contributors:                 993
-
-This release includes the following securify fix:
-
- o POP3/IMAP/SMTP SASL buffer overflow vulnerability [17]
 
 This release includes the following changes:
 
- o test: offer "automake" output and check for perl better
+ o URL parser: IPv6 zone identifiers are now supported
- o always-multi: always use non-blocking internals [1]
+ o CURLOPT_PROXYHEADER: set headers for proxy-only
- o imap: Added support for sasl digest-md5 authentication
+ o CURLOPT_HEADEROPT: added
- o imap: Added support for sasl cram-md5 authentication
+ o curl: add --proxy-header
- o imap: Added support for sasl ntlm authentication
+ o sasl: Added support for DIGEST-MD5 via Windows SSPI
- o imap: Added support for sasl login authentication
+ o sasl: Added DIGEST-MD5 qop-option validation in native challange handling
- o imap: Added support for sasl plain text authentication
+ o imap: Expanded mailbox SEARCH support to use URL query strings [7]
- o imap: Added support for login disabled server capability
+ o imap: Extended FETCH support to include PARTIAL URL specifier [7]
- o mk-ca-bundle: add -f, support passing to stdout and more [5]
+ o nss: implement non-blocking SSL handshake
- o writeout: -w now supports remote_ip/port and local_ip/port
+ o build: Reworked Visual Studio project files
+ o poll: enable poll on darwin13
+ o mk-ca-bundle: added -p
+ o libtests: add a wait_ms() function
 
 This release includes the following bugfixes:
 
- o nss: prevent NSS from crashing on client auth hook failure
+ o mkhelp: generate code for --disable-manual as well [1]
- o darwinssl: Fixed inability to disable peer verification on Snow Leopard
+ o hostcheck: added a system include to define struct in_addr
-   and Lion
+ o winbuild: added warnless.c to fix build
- o curl_multi_remove_handle: fix memory leak triggered with CURLOPT_RESOLVE
+ o Makefile.vc6: added warnless.c to fix build
- o SCP: relative path didn't work as documented [7]
+ o smtp: Fixed login denied when server doesn't support AUTH capability [2]
- o setup_once.h: HP-UX <sys/socket.h> issue workaround
+ o smtp: Fixed login denied with a RFC-821 based server [2]
- o configure: fix cross pkg-config detection
+ o curl: stop interpreting IPv6 literals as glob patterns
- o runtests: Do not add undefined values to @INC
+ o http2: remove _DRAFT09 from the NPN_HTTP2 enum
- o build: fix compilation with CURL_DISABLE_CRYPTO_AUTH flag
+ o http2: let openssl mention the exact protocol negotiated
- o multi: fix re-sending request on early connection close
+ o http2+openssl: fix compiler warnings in ALPN using code
- o HTTP: remove stray CRLF in chunk-encoded content-free request bodies
+ o ftp: in passive data connect wait for happy eyeballs sockets [3]
- o build: fix AIX compilation and usage of events/revents
+ o HTTP: don't send Content-Length: 0 _and_ Expect: 100-continue [4]
- o VC Makefiles: add missing hostcheck
+ o http2: Compile with current nghttp2, which supports h2-11 [5]
- o nss: clear session cache if a client certificate from file is used
+ o http_negotiate_sspi: Fixed compilation when USE_HTTP_NEGOTIATE not defined
- o nss: fix error messages for CURLE_SSL_{CACERT,CRL}_BADFILE
+ o strerror: fix comment about vxworks' strerror_r buffer size [6]
- o fix HTTP CONNECT tunnel establishment upon delayed response [2]
+ o url: only use if_nametoindex() if IFNAMSIZ is available
- o --libcurl: fix for non-zero default options
+ o imap: Fixed untagged response detection when no data after command
- o FTP: reject illegal port numbers in EPSV 229 responses
+ o various: fix possible dereference of null pointer
- o build: use per-target '_CPPFLAGS' for those currently using default
+ o various: fix use of uninitialized variable
- o configure: fix automake 1.13 compatibility [6]
+ o various: fix use of non-null terminated strings
- o curl: ignore SIGPIPE [4]
+ o telnet.c: check sscanf results before passing them to snprintf
- o pop3: Added support for non-blocking SSL upgrade
+ o parsedate.c: check sscanf result before passing it to strlen
- o pop3: Fixed default authentication detection
+ o sockfilt.c: free memory in case of memory allocation errors
- o imap: Fixed usernames and passwords that contain escape characters
+ o sockfilt.c: ignore non-key-events and continue waiting for input
- o packages/DOS/common.dj: remove COFF debug info generation [3]
+ o sockfilt.c: properly handle disk files, pipes and character input
- o imap/pop3/smtp: Fixed failure detection during TLS upgrade [8]
+ o sockfilt.c: fixed getting stuck waiting for MinGW stdin pipe
- o pop3: Fixed no known authentication mechanism when fallback is required [9]
+ o sockfilt.c: clean up threaded approach and add documentation
- o formadd: reject trying to read a directory where a file is expected [10]
+ o configure: use the nghttp2 path correctly with pkg-config [8]
- o formpost: support quotes, commas and semicolon in file names [11]
+ o curl_global_init_mem: bump initialized even if already initialized [9]
- o docs: update the comments about loading CA certs with NSS [12]
+ o gtls: fix NULL pointer dereference [10]
- o docs: fix typos in man pages [13]
+ o cyassl: Use error-ssl.h when available
- o darwinssl: Fix bug where packets were sometimes transmitted twice [14]
+ o handler: make 'protocol' always specified as a single bit [11]
- o winbuild: include version info for .dll .exe [15]
+ o INFILESIZE: fields in UserDefined must not be changed run-time
- o schannel: Removed extended error connection setup flag [16]
+ o openssl: biomem->data is not zero terminated
- o VMS: fix and generate the VMS build config
+ o config-win32.h: Fixed HAVE_LONGLONG for Visual Studio .NET 2003 and up
+ o curl_ntlm_core: Fixed use of long long for VC6 and VC7
+ o SNI: strip off a single trailing dot from host name [12]
+ o curl: bail on cookie use when built with disabled cookies
+ o curl_easy_setopt.3: added the proto for CURLOPT_SSH_KNOWNHOSTS
+ o curl_multi_cleanup: ignore SIGPIPE better [13]
+ o schannel: don't use the connect-timeout during send [14]
+ o mprintf: allow %.s with data not being zero terminated
+ o tool_help: Fixed missing --login-options option
+ o configure: Don't set LD_LIBRARY_PATH when cross-compiling
+ o http: auth failure on duplicated 'WWW-Authenticate: Negotiate' header [15]
+ o cacertinmem: fix memory leak [16]
+ o lib1506: make sure the transfers are not within the same ms [17]
+ o Makefile.b32: Fixed for vtls changes [18]
+ o sasl: Fixed missing qop in the client's challenge-response message
+ o openssl: unbreak PKCS12 support [19]
+ o darwinssl: fix potential crash with a P12 file [20]
+ o timers: fix timer regression involving redirects / reconnects [21]
+ o CURLINFO_SSL_VERIFYRESULT: made more reliable [22]
+ o HTTP: fixed connection re-use [23]
+ o configure: add SPNEGO to supported features [24]
+ o configure: add GSS-API to supported features [25]
+ o ALPN: fix typo in http/1.1 identifier
+ o http2: make connection re-use work [26]
 
 This release includes the following known bugs:
 
@@ -69,32 +90,41 @@ 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:
 
- Nick Zitzmann, Colin Watson, Fabian Keil, Kamil Dudka, Lijo Antony,
+  Aaro Koskinen, Cody Mack, Damian Dixon, Dan Fandrich, Daniel Johnson,
- Linus Nielsen Feltzing, Marc Hoersken, Stanislav Ivochkin, Steve Holme,
+  Daniel Stenberg, David Woodhouse, Dilyan Palauzov, Fabian Frank,
- Yang Tse, Balaji Parasuram, Dan Fandrich, Bob Relyea, Gisle Vanem,
+  Ivo Bellin Salarin, Jeff King, Jeroen Koekkoek, Jon Torrey, Kamil Dudka,
- Yves Arrouye, Kai Engert, Lluís Batlle i Rossell, Jirí Hruka,
+  Larry Lin, Leon Winter, Maciej Puzio, Marc Hoersken, Michael Osipov,
- John E. Malmberg, Tor Arntsen, Matt Arsenault, Sergei Nikulov,
+  Nick Zitzmann, Patrick Watson, Paul Marks, Radu Simionescu, Remi Gacogne,
- Guenter Knauf, Craig Davison, Ulrich Doehner, Jiri Jaburek, Bruno de Carvalho,
+  Ryan Braud, Steve Holme, Tatsuhiro Tsujikawa, Till Maas, Tom Sparrow,
- Eldar Zaitov
+  Török Edwin, Vijay Panghal,
 
         Thanks! (and sorry if I forgot to mention someone)
 
 References to bug reports and discussions on issues:
 
- [1] = http://daniel.haxx.se/blog/2013/01/17/internally-were-all-multi-now/
+ [1] = http://curl.haxx.se/bug/view.cgi?id=1350
- [2] = http://curl.haxx.se/mail/lib-2013-01/0191.html
+ [2] = http://curl.haxx.se/mail/lib-2014-03/0173.html
- [3] = http://curl.haxx.se/mail/lib-2013-01/0130.html
+ [3] = http://curl.haxx.se/mail/lib-2014-02/0135.html (ruined)
- [4] = http://curl.haxx.se/bug/view.cgi?id=1180
+ [4] = http://curl.haxx.se/bug/view.cgi?id=1349
- [5] = http://curl.haxx.se/mail/lib-2013-01/0045.html
+ [5] = http://curl.haxx.se/mail/lib-2014-04/0053.html
- [6] = http://curl.haxx.se/mail/lib-2012-12/0246.html
+ [6] = http://curl.haxx.se/mail/lib-2014-04/0063.html
- [7] = http://curl.haxx.se/bug/view.cgi?id=1173
+ [7] = http://curl.haxx.se/mail/lib-2014-04/0067.html
- [8] = http://curl.haxx.se/mail/lib-2013-01/0250.html
+ [8] = http://curl.haxx.se/mail/lib-2014-04/0159.html
- [9] = http://curl.haxx.se/mail/lib-2013-02/0004.html
+ [9] = http://curl.haxx.se/bug/view.cgi?id=1362
- [10] = http://curl.haxx.se/mail/archive-2013-01/0017.html
+ [10] = http://curl.haxx.se/mail/lib-2014-04/0145.html
- [11] = http://curl.haxx.se/bug/view.cgi?id=1171
+ [11] = https://github.com/bagder/curl/pull/97
- [12] = https://bugzilla.redhat.com/696783
+ [12] = http://curl.haxx.se/mail/lib-2014-04/0161.html
- [13] = https://bugzilla.redhat.com/896544
+ [13] = http://thread.gmane.org/gmane.comp.version-control.git/238242
- [14] = http://curl.haxx.se/mail/lib-2013-01/0295.html
+ [14] = http://curl.haxx.se/bug/view.cgi?id=1352
- [15] = http://curl.haxx.se/bug/view.cgi?id=1186
+ [15] = https://bugzilla.redhat.com/1093348
- [16] = http://curl.haxx.se/bug/view.cgi?id=1187
+ [16] = http://curl.haxx.se/bug/view.cgi?id=1368
- [17] = http://curl.haxx.se/docs/adv_20130206.html
+ [17] = http://curl.haxx.se/mail/lib-2014-05/0081.html
+ [18] = http://curl.haxx.se/mail/lib-2014-05/0025.html
+ [19] = http://curl.haxx.se/bug/view.cgi?id=1371
+ [20] = http://curl.haxx.se/bug/view.cgi?id=1369
+ [21] = http://curl.haxx.se/mail/lib-2014-05/0147.html
+ [22] = http://curl.haxx.se/mail/lib-2014-04/0203.html
+ [23] = http://curl.haxx.se/mail/lib-2014-05/0127.html
+ [24] = http://curl.haxx.se/bug/view.cgi?id=1343
+ [25] = http://curl.haxx.se/bug/view.cgi?id=1344
+ [26] = http://curl.haxx.se/bug/view.cgi?id=1374

TODO-RELEASE

@@ -1,14 +1,4 @@
-To be addressed in 7.29
+To be addressed in ...
 =======================
 
-310 - a new authentication callback
-
-312 - custom Content-Length appears in CONNECT, solve it by offering a
-      separate option to provide headers for the CONNECT request:
-      http://curl.haxx.se/mail/lib-2012-09/0059.html
-
-317 - CURLINFO_SSL_TRUST to return SSL-specific data for a darwinssl build
-
-322 - pipelining improvements
-
 327 - 

acinclude.m4

@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 1998 - 2013, 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
@@ -1597,213 +1597,6 @@ AC_DEFUN([CURL_CHECK_FUNC_SEND], [
   fi
 ])
 
-
-dnl CURL_CHECK_FUNC_RECVFROM
-dnl -------------------------------------------------
-dnl Test if the socket recvfrom() function is available,
-dnl and check its return type and the types of its
-dnl arguments. If the function succeeds HAVE_RECVFROM
-dnl will be defined, defining the types of the arguments
-dnl in RECVFROM_TYPE_ARG1, RECVFROM_TYPE_ARG2, and so on
-dnl to RECVFROM_TYPE_ARG6, defining also the type of the
-dnl function return value in RECVFROM_TYPE_RETV.
-dnl Notice that the types returned for pointer arguments
-dnl will actually be the type pointed by the pointer.
-
-AC_DEFUN([CURL_CHECK_FUNC_RECVFROM], [
-  AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK])dnl
-  AC_REQUIRE([CURL_CHECK_HEADER_WINSOCK2])dnl
-  AC_CHECK_HEADERS(sys/types.h sys/socket.h)
-  #
-  AC_MSG_CHECKING([for recvfrom])
-  AC_LINK_IFELSE([
-    AC_LANG_PROGRAM([[
-#undef inline
-#ifdef HAVE_WINDOWS_H
-#ifndef WIN32_LEAN_AND_MEAN
-#define WIN32_LEAN_AND_MEAN
-#endif
-#include <windows.h>
-#ifdef HAVE_WINSOCK2_H
-#include <winsock2.h>
-#else
-#ifdef HAVE_WINSOCK_H
-#include <winsock.h>
-#endif
-#endif
-#else
-#ifdef HAVE_SYS_TYPES_H
-#include <sys/types.h>
-#endif
-#ifdef HAVE_SYS_SOCKET_H
-#include <sys/socket.h>
-#endif
-#endif
-    ]],[[
-      recvfrom(0, 0, 0, 0, 0, 0);
-    ]])
-  ],[
-    AC_MSG_RESULT([yes])
-    curl_cv_recvfrom="yes"
-  ],[
-    AC_MSG_RESULT([no])
-    curl_cv_recvfrom="no"
-  ])
-  #
-  if test "$curl_cv_recvfrom" = "yes"; then
-    AC_CACHE_CHECK([types of args and return type for recvfrom],
-      [curl_cv_func_recvfrom_args], [
-      curl_cv_func_recvfrom_args="unknown"
-      for recvfrom_retv in 'int' 'ssize_t'; do
-        for recvfrom_arg1 in 'int' 'ssize_t' 'SOCKET'; do
-          for recvfrom_arg2 in 'char *' 'void *'; do
-            for recvfrom_arg3 in 'size_t' 'int' 'socklen_t' 'unsigned int'; do
-              for recvfrom_arg4 in 'int' 'unsigned int'; do
-                for recvfrom_arg5 in 'struct sockaddr *' 'void *' 'const struct sockaddr *'; do
-                  for recvfrom_arg6 in 'socklen_t *' 'int *' 'unsigned int *' 'size_t *' 'void *'; do
-                    if test "$curl_cv_func_recvfrom_args" = "unknown"; then
-                      AC_COMPILE_IFELSE([
-                        AC_LANG_PROGRAM([[
-#undef inline
-#ifdef HAVE_WINDOWS_H
-#ifndef WIN32_LEAN_AND_MEAN
-#define WIN32_LEAN_AND_MEAN
-#endif
-#include <windows.h>
-#ifdef HAVE_WINSOCK2_H
-#include <winsock2.h>
-#else
-#ifdef HAVE_WINSOCK_H
-#include <winsock.h>
-#endif
-#endif
-#define RECVFROMCALLCONV PASCAL
-#else
-#ifdef HAVE_SYS_TYPES_H
-#include <sys/types.h>
-#endif
-#ifdef HAVE_SYS_SOCKET_H
-#include <sys/socket.h>
-#endif
-#define RECVFROMCALLCONV
-#endif
-                          extern $recvfrom_retv RECVFROMCALLCONV
-                          recvfrom($recvfrom_arg1, $recvfrom_arg2,
-                                   $recvfrom_arg3, $recvfrom_arg4,
-                                   $recvfrom_arg5, $recvfrom_arg6);
-                        ]],[[
-                          $recvfrom_arg1 s=0;
-                          $recvfrom_arg2 buf=0;
-                          $recvfrom_arg3 len=0;
-                          $recvfrom_arg4 flags=0;
-                          $recvfrom_arg5 addr=0;
-                          $recvfrom_arg6 addrlen=0;
-                          $recvfrom_retv res=0;
-                          res = recvfrom(s, buf, len, flags, addr, addrlen);
-                        ]])
-                      ],[
-                        curl_cv_func_recvfrom_args="$recvfrom_arg1,$recvfrom_arg2,$recvfrom_arg3,$recvfrom_arg4,$recvfrom_arg5,$recvfrom_arg6,$recvfrom_retv"
-                      ])
-                    fi
-                  done
-                done
-              done
-            done
-          done
-        done
-      done
-    ]) # AC-CACHE-CHECK
-    # Nearly last minute change for this release starts here
-    AC_DEFINE_UNQUOTED(HAVE_RECVFROM, 1,
-      [Define to 1 if you have the recvfrom function.])
-    ac_cv_func_recvfrom="yes"
-    # Nearly last minute change for this release ends here
-    if test "$curl_cv_func_recvfrom_args" = "unknown"; then
-      AC_MSG_WARN([Cannot find proper types to use for recvfrom args])
-    else
-      recvfrom_prev_IFS=$IFS; IFS=','
-      set dummy `echo "$curl_cv_func_recvfrom_args" | sed 's/\*/\*/g'`
-      IFS=$recvfrom_prev_IFS
-      shift
-      #
-      recvfrom_ptrt_arg2=$[2]
-      recvfrom_qual_ptrt_arg5=$[5]
-      recvfrom_ptrt_arg6=$[6]
-      #
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG1, $[1],
-        [Define to the type of arg 1 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG3, $[3],
-        [Define to the type of arg 3 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG4, $[4],
-        [Define to the type of arg 4 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_RETV, $[7],
-        [Define to the function return type for recvfrom.])
-      #
-      prev_sh_opts=$-
-      #
-      case $prev_sh_opts in
-        *f*)
-          ;;
-        *)
-          set -f
-          ;;
-      esac
-      #
-      case "$recvfrom_qual_ptrt_arg5" in
-        const*)
-          recvfrom_qual_arg5=const
-          recvfrom_ptrt_arg5=`echo $recvfrom_qual_ptrt_arg5 | sed 's/^const //'`
-        ;;
-        *)
-          recvfrom_qual_arg5=
-          recvfrom_ptrt_arg5=$recvfrom_qual_ptrt_arg5
-        ;;
-      esac
-      #
-      recvfrom_type_arg2=`echo $recvfrom_ptrt_arg2 | sed 's/ \*//'`
-      recvfrom_type_arg5=`echo $recvfrom_ptrt_arg5 | sed 's/ \*//'`
-      recvfrom_type_arg6=`echo $recvfrom_ptrt_arg6 | sed 's/ \*//'`
-      #
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG2, $recvfrom_type_arg2,
-        [Define to the type pointed by arg 2 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_QUAL_ARG5, $recvfrom_qual_arg5,
-        [Define to the type qualifier pointed by arg 5 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG5, $recvfrom_type_arg5,
-        [Define to the type pointed by arg 5 for recvfrom.])
-      AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG6, $recvfrom_type_arg6,
-        [Define to the type pointed by arg 6 for recvfrom.])
-      #
-      if test "$recvfrom_type_arg2" = "void"; then
-        AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG2_IS_VOID, 1,
-          [Define to 1 if the type pointed by arg 2 for recvfrom is void.])
-      fi
-      if test "$recvfrom_type_arg5" = "void"; then
-        AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG5_IS_VOID, 1,
-          [Define to 1 if the type pointed by arg 5 for recvfrom is void.])
-      fi
-      if test "$recvfrom_type_arg6" = "void"; then
-        AC_DEFINE_UNQUOTED(RECVFROM_TYPE_ARG6_IS_VOID, 1,
-          [Define to 1 if the type pointed by arg 6 for recvfrom is void.])
-      fi
-      #
-      case $prev_sh_opts in
-        *f*)
-          ;;
-        *)
-          set +f
-          ;;
-      esac
-      #
-      AC_DEFINE_UNQUOTED(HAVE_RECVFROM, 1,
-        [Define to 1 if you have the recvfrom function.])
-      ac_cv_func_recvfrom="yes"
-    fi
-  else
-    AC_MSG_WARN([Unable to link function recvfrom])
-  fi
-])
-
-
 dnl CURL_CHECK_MSG_NOSIGNAL
 dnl -------------------------------------------------
 dnl Check for MSG_NOSIGNAL
@@ -2827,46 +2620,50 @@ AC_HELP_STRING([--without-ca-path], [Don't use a default CA path]),
     capath="$want_capath"
     ca="no"
   else
-    dnl neither of --with-ca-* given
     dnl first try autodetecting a CA bundle , then a CA path
     dnl both autodetections can be skipped by --without-ca-*
     ca="no"
     capath="no"
-    if test "x$want_ca" = "xunset"; then
+    if test "x$cross_compiling" != "xyes"; then
-      dnl the path we previously would have installed the curl ca bundle
+      dnl NOT cross-compiling and...
-      dnl to, and thus we now check for an already existing cert in that place
+      dnl neither of the --with-ca-* options are provided
-      dnl in case we find no other
+      if test "x$want_ca" = "xunset"; then
-      if test "x$prefix" != xNONE; then
+        dnl the path we previously would have installed the curl ca bundle
-        cac="${prefix}/share/curl/curl-ca-bundle.crt"
+        dnl to, and thus we now check for an already existing cert in that
-      else
+        dnl place in case we find no other
-        cac="$ac_default_prefix/share/curl/curl-ca-bundle.crt"
+        if test "x$prefix" != xNONE; then
-      fi
+          cac="${prefix}/share/curl/curl-ca-bundle.crt"
+        else
+          cac="$ac_default_prefix/share/curl/curl-ca-bundle.crt"
+        fi
 
-      for a in /etc/ssl/certs/ca-certificates.crt \
+        for a in /etc/ssl/certs/ca-certificates.crt \
-               /etc/pki/tls/certs/ca-bundle.crt \
+                 /etc/pki/tls/certs/ca-bundle.crt \
-               /usr/share/ssl/certs/ca-bundle.crt \
+                 /usr/share/ssl/certs/ca-bundle.crt \
-               /usr/local/share/certs/ca-root.crt \
+                 /usr/local/share/certs/ca-root.crt \
-               /etc/ssl/cert.pem \
+                 /etc/ssl/cert.pem \
-               "$cac"; do
+                 "$cac"; do
-        if test -f "$a"; then
+          if test -f "$a"; then
-          ca="$a"
+            ca="$a"
-          break
+            break
-        fi
+          fi
-      done
+        done
-    fi
+      fi
-    if test "x$want_capath" = "xunset" -a "x$ca" = "xno" -a \
+      if test "x$want_capath" = "xunset" -a "x$ca" = "xno" -a \
-            "x$OPENSSL_ENABLED" = "x1"; then
+              "x$OPENSSL_ENABLED" = "x1"; then
-      for a in /etc/ssl/certs/; do
+        for a in /etc/ssl/certs/; do
-        if test -d "$a" && ls "$a"/[[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]].0 >/dev/null 2>/dev/null; then
+          if test -d "$a" && ls "$a"/[[0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f][0-9a-f]].0 >/dev/null 2>/dev/null; then
-          capath="$a"
+            capath="$a"
-          break
+            break
-        fi
+          fi
-      done
+        done
+      fi
+    else
+      dnl no option given and cross-compiling
+      AC_MSG_WARN([skipped the ca-cert path detection when cross-compiling])
     fi
   fi
 
-
-
   if test "x$ca" != "xno"; then
     CURL_CA_BUNDLE='"'$ca'"'
     AC_DEFINE_UNQUOTED(CURL_CA_BUNDLE, "$ca", [Location of default ca bundle])

configure.ac

@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 1998 - 2014, 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
@@ -31,7 +31,7 @@ XC_OVR_ZZ60
 CURL_OVERRIDE_AUTOCONF
 
 dnl configure script copyright
-AC_COPYRIGHT([Copyright (c) 1998 - 2013 Daniel Stenberg, <daniel@haxx.se>
+AC_COPYRIGHT([Copyright (c) 1998 - 2014 Daniel Stenberg, <daniel@haxx.se>
 This configure script may be copied, distributed and modified under the
 terms of the curl license; see COPYING for more details])
 
@@ -126,7 +126,7 @@ fi
 dnl figure out the libcurl version
 CURLVERSION=`$SED -ne 's/^#define LIBCURL_VERSION "\(.*\)"/\1/p' ${srcdir}/include/curl/curlver.h`
 XC_CHECK_PROG_CC
-AM_INIT_AUTOMAKE
+XC_AUTOMAKE
 AC_MSG_CHECKING([curl version])
 AC_MSG_RESULT($CURLVERSION)
 
@@ -150,7 +150,6 @@ dnl initialize all the info variables
     curl_ssl_msg="no      (--with-{ssl,gnutls,nss,polarssl,cyassl,axtls,winssl,darwinssl} )"
     curl_ssh_msg="no      (--with-libssh2)"
    curl_zlib_msg="no      (--with-zlib)"
-   curl_krb4_msg="no      (--with-krb4*)"
     curl_gss_msg="no      (--with-gssapi)"
  curl_spnego_msg="no      (--with-spnego)"
 curl_tls_srp_msg="no      (--enable-tls-srp)"
@@ -198,74 +197,50 @@ CURL_CONFIGURE_REENTRANT
 dnl check for how to do large files
 AC_SYS_LARGEFILE
 
-dnl support building of Windows DLLs
+XC_LIBTOOL
-AC_LIBTOOL_WIN32_DLL
 
-dnl force libtool to build static libraries with PIC on AMD64-Linux & FreeBSD
+#
-AC_MSG_CHECKING([if arch-OS host is AMD64-Linux/FreeBSD (to build static libraries with PIC)])
+# Automake conditionals based on libtool related checks
-case $host in
+#
-  x86_64*linux*|amd64*freebsd*|ia64*freebsd*)
-    AC_MSG_RESULT([yes])
-    with_pic=yes
-    ;;
-  *)
-    AC_MSG_RESULT([no])
-    ;;
-esac
 
-AC_MSG_CHECKING([if compiler is icc (to build with PIC)])
+AM_CONDITIONAL([CURL_LT_SHLIB_USE_VERSION_INFO],
-case $CC in
+  [test "x$xc_lt_shlib_use_version_info" = 'xyes'])
-  icc | */icc)
+AM_CONDITIONAL([CURL_LT_SHLIB_USE_NO_UNDEFINED],
-    AC_MSG_RESULT([yes])
+  [test "x$xc_lt_shlib_use_no_undefined" = 'xyes'])
-    with_pic=yes
+AM_CONDITIONAL([CURL_LT_SHLIB_USE_MIMPURE_TEXT],
-    ;;
+  [test "x$xc_lt_shlib_use_mimpure_text" = 'xyes'])
-  *)
-    AC_MSG_RESULT([no])
-    ;;
-esac
 
-dnl libtool setup
+#
-AC_PROG_LIBTOOL
+# Due to libtool and automake machinery limitations of not allowing
+# specifying separate CPPFLAGS or CFLAGS when compiling objects for
+# inclusion of these in shared or static libraries, we are forced to
+# build using separate configure runs for shared and static libraries
+# on systems where different CPPFLAGS or CFLAGS are mandatory in order
+# to compile objects for each kind of library. Notice that relying on
+# the '-DPIC' CFLAG that libtool provides is not valid given that the
+# user might for example choose to build static libraries with PIC.
+#
 
-AC_MSG_CHECKING([if we need -mimpure-text])
+#
-mimpure=no
+# Make our Makefile.am files use the staticlib CPPFLAG only when strictly
-case $host in
+# targeting a static library and not building its shared counterpart.
-  *-*-solaris2*)
+#
-    if test "$GCC" = "yes"; then
+
-      mimpure="yes"
+AM_CONDITIONAL([USE_CPPFLAG_CURL_STATICLIB],
-    fi
+  [test "x$xc_lt_build_static_only" = 'xyes'])
-    ;;
+
-  *)
+#
-    ;;
+# Make staticlib CPPFLAG variable and its definition visible in output
-esac
+# files unconditionally, providing an empty definition unless strictly
-AC_MSG_RESULT($mimpure)
+# targeting a static library and not building its shared counterpart.
-AM_CONDITIONAL(MIMPURE, test x$mimpure = xyes)
+#
+
+CPPFLAG_CURL_STATICLIB=
+if test "x$xc_lt_build_static_only" = 'xyes'; then
+  CPPFLAG_CURL_STATICLIB='-DCURL_STATICLIB'
+fi
+AC_SUBST([CPPFLAG_CURL_STATICLIB])
 
-AC_MSG_CHECKING([if we need BUILDING_LIBCURL])
-use_cppflag_building_libcurl="no"
-use_cppflag_curl_staticlib="no"
-CPPFLAG_CURL_STATICLIB=""
-case $host in
-  *-*-mingw*)
-    AC_MSG_RESULT(yes)
-    use_cppflag_building_libcurl="yes"
-    AC_MSG_CHECKING([if we need CURL_STATICLIB])
-    if test "X$enable_shared" = "Xno"
-    then
-      AC_MSG_RESULT(yes)
-      use_cppflag_curl_staticlib="yes"
-      CPPFLAG_CURL_STATICLIB="-DCURL_STATICLIB"
-    else
-      AC_MSG_RESULT(no)
-    fi
-    ;;
-  *)
-    AC_MSG_RESULT(no)
-    ;;
-esac
-AM_CONDITIONAL(USE_CPPFLAG_BUILDING_LIBCURL, test x$use_cppflag_building_libcurl = xyes)
-AM_CONDITIONAL(USE_CPPFLAG_CURL_STATICLIB, test x$use_cppflag_curl_staticlib = xyes)
-AC_SUBST(CPPFLAG_CURL_STATICLIB)
 
 # Determine whether all dependent libraries must be specified when linking
 if test "X$enable_shared" = "Xyes" -a "X$link_all_deplibs" = "Xno"
@@ -277,10 +252,6 @@ fi
 AC_SUBST(REQUIRE_LIB_DEPS)
 AM_CONDITIONAL(USE_EXPLICIT_LIB_DEPS, test x$REQUIRE_LIB_DEPS = xyes)
 
-dnl The install stuff has already been taken care of by the automake stuff
-dnl AC_PROG_INSTALL
-AC_PROG_MAKE_SET
-
 dnl check if there's a way to force code inline
 AC_C_INLINE
 
@@ -311,9 +282,6 @@ CURL_CHECK_COMPILER_ARRAY_SIZE_NEGATIVE
 CURL_CHECK_COMPILER_PROTOTYPE_MISMATCH
 CURL_CHECK_COMPILER_SYMBOL_HIDING
 
-CURL_CHECK_NO_UNDEFINED
-AM_CONDITIONAL(NO_UNDEFINED, test x$need_no_undefined = xyes)
-
 CURL_CHECK_CURLDEBUG
 AM_CONDITIONAL(CURLDEBUG, test x$want_curldebug = xyes)
 
@@ -1097,6 +1065,7 @@ AC_HELP_STRING([--disable-ipv6],[Disable ipv6 support]),
   AC_TRY_RUN([ /* is AF_INET6 available? */
 #include <sys/types.h>
 #include <sys/socket.h>
+#include <stdlib.h> /* for exit() */
 main()
 {
  if (socket(AF_INET6, SOCK_STREAM, 0) < 0)
@@ -1165,101 +1134,6 @@ no)
         ;;
 esac
 
-dnl **********************************************************************
-dnl Check for the presence of Kerberos4 libraries and headers
-dnl **********************************************************************
-
-AC_ARG_WITH(krb4-includes,
-AC_HELP_STRING([--with-krb4-includes=DIR],
-               [Specify location of kerberos4 headers]),[
- CPPFLAGS="$CPPFLAGS -I$withval"
- KRB4INC="$withval"
- want_krb4=yes
- ])
-
-AC_ARG_WITH(krb4-libs,
-AC_HELP_STRING([--with-krb4-libs=DIR],[Specify location of kerberos4 libs]),[
- LDFLAGS="$LDFLAGS -L$withval"
- KRB4LIB="$withval"
- want_krb4=yes
- ])
-
-
-OPT_KRB4=off
-AC_ARG_WITH(krb4,dnl
-AC_HELP_STRING([--with-krb4=DIR],[where to look for Kerberos4]),[
-  OPT_KRB4="$withval"
-  if test X"$OPT_KRB4" != Xno; then
-    want_krb4="yes"
-    if test X"$OPT_KRB4" != Xyes; then
-      LDFLAGS="$LDFLAGS -L$OPT_KRB4/lib$libsuff"
-      KRB4LIB="$OPT_KRB4/lib$libsuff"
-      CPPFLAGS="$CPPFLAGS -I$OPT_KRB4/include"
-      KRB4INC="$OPT_KRB4/include"
-    fi
-  fi
- ])
-
-AC_MSG_CHECKING([if Kerberos4 support is requested])
-
-if test "$want_krb4" = yes
-then
-  if test "$ipv6" = "yes"; then
-    echo krb4 is not compatible with IPv6
-    exit 1
-  fi
-  AC_MSG_RESULT(yes)
-
-  dnl Check for & handle argument to --with-krb4
-
-  AC_MSG_CHECKING(where to look for Kerberos4)
-  if test X"$OPT_KRB4" = Xyes
-  then
-    AC_MSG_RESULT([defaults])
-  else
-    AC_MSG_RESULT([libs in $KRB4LIB, headers in $KRB4INC])
-  fi
-
-  dnl Check for DES library
-  AC_CHECK_LIB(des, des_pcbc_encrypt,
-  [
-    AC_CHECK_HEADERS(des.h)
-
-    dnl resolv lib?
-    AC_CHECK_FUNC(res_search, , [AC_CHECK_LIB(resolv, res_search)])
-
-    dnl Check for the Kerberos4 library
-    AC_CHECK_LIB(krb, krb_net_read,
-    [
-      dnl Check for header files
-      AC_CHECK_HEADERS(krb.h)
-
-      dnl we found the required libraries, add to LIBS
-      LIBS="-lkrb -lcom_err -ldes $LIBS"
-
-      dnl Check for function krb_get_our_ip_for_realm
-      dnl this is needed for NAT networks
-      AC_CHECK_FUNCS(krb_get_our_ip_for_realm)
-
-      dnl add define KRB4
-      AC_DEFINE(HAVE_KRB4, 1,
-      [if you have the Kerberos4 libraries (including -ldes)])
-
-      dnl substitute it too!
-      KRB4_ENABLED=1
-      AC_SUBST(KRB4_ENABLED)
-
-      curl_krb4_msg="enabled"
-
-      dnl the krb4 stuff needs a strlcpy()
-      AC_CHECK_FUNCS(strlcpy)
-
-    ])
-  ])
-else
-  AC_MSG_RESULT(no)
-fi
-
 dnl **********************************************************************
 dnl Check for FBopenssl(SPNEGO) libraries
 dnl **********************************************************************
@@ -1299,26 +1173,26 @@ dnl **********************************************************************
 dnl Check for GSS-API libraries
 dnl **********************************************************************
 
-dnl check for gss stuff in the /usr as default
+dnl check for GSS-API stuff in the /usr as default
 
 GSSAPI_ROOT="/usr"
 AC_ARG_WITH(gssapi-includes,
   AC_HELP_STRING([--with-gssapi-includes=DIR],
-                 [Specify location of GSSAPI header]),
+                 [Specify location of GSS-API headers]),
   [ GSSAPI_INCS="-I$withval"
     want_gss="yes" ]
 )
 
 AC_ARG_WITH(gssapi-libs,
   AC_HELP_STRING([--with-gssapi-libs=DIR],
-                 [Specify location of GSSAPI libs]),
+                 [Specify location of GSS-API libs]),
   [ GSSAPI_LIB_DIR="-L$withval"
     want_gss="yes" ]
 )
 
 AC_ARG_WITH(gssapi,
   AC_HELP_STRING([--with-gssapi=DIR],
-                 [Where to look for GSSAPI]), [
+                 [Where to look for GSS-API]), [
   GSSAPI_ROOT="$withval"
   if test x"$GSSAPI_ROOT" != xno; then
     want_gss="yes"
@@ -1330,7 +1204,7 @@ AC_ARG_WITH(gssapi,
 ])
 
 save_CPPFLAGS="$CPPFLAGS"
-AC_MSG_CHECKING([if GSSAPI support is requested])
+AC_MSG_CHECKING([if GSS-API support is requested])
 if test x"$want_gss" = xyes; then
   AC_MSG_RESULT(yes)
 
@@ -1347,7 +1221,7 @@ if test x"$want_gss" = xyes; then
   AC_CHECK_HEADER(gss.h,
     [
       dnl found in the given dirs
-      AC_DEFINE(HAVE_GSSGNU, 1, [if you have the GNU gssapi libraries])
+      AC_DEFINE(HAVE_GSSGNU, 1, [if you have GNU GSS])
       gnu_gss=yes
     ],
     [
@@ -1368,19 +1242,19 @@ AC_INCLUDES_DEFAULT
         AC_CHECK_HEADER(gssapi.h,
             [
               dnl found
-              AC_DEFINE(HAVE_GSSHEIMDAL, 1, [if you have the Heimdal gssapi libraries])
+              AC_DEFINE(HAVE_GSSHEIMDAL, 1, [if you have Heimdal])
             ],
             [
               dnl no header found, disabling GSS
               want_gss=no
-              AC_MSG_WARN(disabling GSSAPI since no header files was found)
+              AC_MSG_WARN(disabling GSS-API support since no header files were found)
             ]
           )
       else
         dnl MIT found
-        AC_DEFINE(HAVE_GSSMIT, 1, [if you have the MIT gssapi libraries])
+        AC_DEFINE(HAVE_GSSMIT, 1, [if you have MIT Kerberos])
-        dnl check if we have a really old MIT kerberos (<= 1.2)
+        dnl check if we have a really old MIT Kerberos version (<= 1.2)
-        AC_MSG_CHECKING([if gssapi headers declare GSS_C_NT_HOSTBASED_SERVICE])
+        AC_MSG_CHECKING([if GSS-API headers declare GSS_C_NT_HOSTBASED_SERVICE])
         AC_COMPILE_IFELSE([
           AC_LANG_PROGRAM([[
 #include <gssapi/gssapi.h>
@@ -1398,7 +1272,7 @@ AC_INCLUDES_DEFAULT
         ],[
           AC_MSG_RESULT([no])
           AC_DEFINE(HAVE_OLD_GSSMIT, 1,
-            [if you have an old MIT gssapi library, lacking GSS_C_NT_HOSTBASED_SERVICE])
+            [if you have an old MIT Kerberos version, lacking GSS_C_NT_HOSTBASED_SERVICE])
         ])
       fi
     ]
@@ -1407,9 +1281,9 @@ else
   AC_MSG_RESULT(no)
 fi
 if test x"$want_gss" = xyes; then
-  AC_DEFINE(HAVE_GSSAPI, 1, [if you have the gssapi libraries])
+  AC_DEFINE(HAVE_GSSAPI, 1, [if you have GSS-API libraries])
 
-  curl_gss_msg="enabled (MIT/Heimdal)"
+  curl_gss_msg="enabled (MIT Kerberos/Heimdal)"
 
   if test -n "$gnu_gss"; then
     curl_gss_msg="enabled (GNU GSS)"
@@ -1420,6 +1294,12 @@ if test x"$want_gss" = xyes; then
      *-*-darwin*)
         LIBS="-lgssapi_krb5 -lresolv $LIBS"
         ;;
+     *-hp-hpux*)
+        if test "$GSSAPI_ROOT" != "yes"; then
+           LDFLAGS="$LDFLAGS -L$GSSAPI_ROOT/lib$libsuff"
+        fi
+        LIBS="-lgss $LIBS"
+        ;;
      *)
         if test -f "$GSSAPI_ROOT/bin/krb5-config"; then
            dnl krb5-config doesn't have --libs-only-L or similar, put everything
@@ -1436,7 +1316,14 @@ if test x"$want_gss" = xyes; then
      esac
   else
      LDFLAGS="$LDFLAGS $GSSAPI_LIB_DIR"
-     LIBS="-lgssapi $LIBS"
+     case $host in
+     *-hp-hpux*)
+        LIBS="-lgss $LIBS"
+        ;;
+     *)
+        LIBS="-lgssapi $LIBS"
+        ;;
+     esac
   fi
 else
   CPPFLAGS="$save_CPPFLAGS"
@@ -1707,7 +1594,10 @@ if test "$curl_ssl_msg" = "$init_ssl_msg" && test X"$OPT_SSL" != Xno; then
                     ENGINE_cleanup \
                     CRYPTO_cleanup_all_ex_data \
                     SSL_get_shutdown \
-                    SSLv2_client_method )
+                    SSLv2_client_method \
+                    SSL_CTX_set_next_proto_select_cb \
+                    SSL_CTX_set_alpn_protos \
+                    SSL_CTX_set_alpn_select_cb )
 
     dnl Make an attempt to detect if this is actually yassl's headers and
     dnl OpenSSL emulation layer. We still leave everything else believing
@@ -2110,6 +2000,12 @@ if test "$curl_ssl_msg" = "$init_ssl_msg"; then
     if test "x$USE_CYASSL" = "xyes"; then
       AC_MSG_NOTICE([detected CyaSSL])
 
+      dnl cyassl/ctaocrypt/types.h needs SIZEOF_LONG_LONG defined!
+      AC_CHECK_SIZEOF(long long)
+
+      dnl Versions since at least 2.9.4 renamed error.h to error-ssl.h
+      AC_CHECK_HEADERS(cyassl/error-ssl.h)
+
       LIBS="-lcyassl -lm $LIBS"
 
       if test -n "$cyassllib"; then
@@ -2194,8 +2090,8 @@ if test "$curl_ssl_msg" = "$init_ssl_msg"; then
          CPPFLAGS="$CPPFLAGS $addcflags"
       fi
 
-      dnl The function PK11_CreateGenericObject is needed to load libnsspem.so
+      dnl The function SSL_VersionRangeSet() is needed to enable TLS > 1.0
-      AC_CHECK_LIB(nss3, PK11_CreateGenericObject,
+      AC_CHECK_LIB(nss3, SSL_VersionRangeSet,
        [
        AC_DEFINE(USE_NSS, 1, [if NSS is enabled])
        AC_SUBST(USE_NSS, [1])
@@ -2211,14 +2107,6 @@ if test "$curl_ssl_msg" = "$init_ssl_msg"; then
       if test "x$USE_NSS" = "xyes"; then
         AC_MSG_NOTICE([detected NSS version $version])
 
-        dnl NSS_InitContext() was introduced in NSS 3.12.5 and helps to prevent
-        dnl collisions on NSS initialization/shutdown with other libraries
-        AC_CHECK_FUNC(NSS_InitContext,
-        [
-          AC_DEFINE(HAVE_NSS_INITCONTEXT, 1, [if you have the NSS_InitContext function])
-          AC_SUBST(HAVE_NSS_INITCONTEXT, [1])
-        ])
-
         dnl when shared libs were found in a path that the run-time
         dnl linker doesn't search through, we need to add it to
         dnl LD_LIBRARY_PATH to prevent further configure tests to fail
@@ -2279,10 +2167,11 @@ if test "$curl_ssl_msg" = "$init_ssl_msg"; then
       USE_AXTLS="yes"
       curl_ssl_msg="enabled (axTLS)"
 
-
+      if test "x$cross_compiling" != "xyes"; then
-      LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$LIB_AXTLS"
+        LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$LIB_AXTLS"
-      export LD_LIBRARY_PATH
+        export LD_LIBRARY_PATH
-      AC_MSG_NOTICE([Added $LIB_AXTLS to LD_LIBRARY_PATH])
+        AC_MSG_NOTICE([Added $LIB_AXTLS to LD_LIBRARY_PATH])
+      fi
       ],[
       LDFLAGS="$CLEANLDFLAGS"
       CPPFLAGS="$CLEANCPPFLAGS"
@@ -2293,7 +2182,7 @@ fi
 
 if test "x$OPENSSL_ENABLED$GNUTLS_ENABLED$NSS_ENABLED$POLARSSL_ENABLED$AXTLS_ENABLED$CYASSL_ENABLED$WINSSL_ENABLED$DARWINSSL_ENABLED" = "x"; then
   AC_MSG_WARN([SSL disabled, you will not be able to use HTTPS, FTPS, NTLM and more.])
-  AC_MSG_WARN([Use --with-ssl, --with-gnutls, --with-polarssl, --with-cyassl, --with-nss, --with-axtls or --with-winssl to address this.])
+  AC_MSG_WARN([Use --with-ssl, --with-gnutls, --with-polarssl, --with-cyassl, --with-nss, --with-axtls, --with-winssl, or --with-darwinssl to address this.])
 else
   # SSL is enabled, genericly
   AC_SUBST(SSL_ENABLED)
@@ -2584,19 +2473,19 @@ AC_HELP_STRING([--disable-versioned-symbols], [Disable versioned symbols in shar
         AC_MSG_RESULT(yes)
         if test "x$OPENSSL_ENABLED" = "x1"; then
           versioned_symbols_flavour="OPENSSL_"
-        elif test "x$GNUTLS_ENABLED" == "x1"; then
+        elif test "x$GNUTLS_ENABLED" = "x1"; then
           versioned_symbols_flavour="GNUTLS_"
-        elif test "x$NSS_ENABLED" == "x1"; then
+        elif test "x$NSS_ENABLED" = "x1"; then
           versioned_symbols_flavour="NSS_"
-        elif test "x$POLARSSL_ENABLED" == "x1"; then
+        elif test "x$POLARSSL_ENABLED" = "x1"; then
           versioned_symbols_flavour="POLARSSL_"
-        elif test "x$CYASSL_ENABLED" == "x1"; then
+        elif test "x$CYASSL_ENABLED" = "x1"; then
           versioned_symbols_flavour="CYASSL_"
-        elif test "x$AXTLS_ENABLED" == "x1"; then
+        elif test "x$AXTLS_ENABLED" = "x1"; then
           versioned_symbols_flavour="AXTLS_"
-        elif test "x$WINSSL_ENABLED" == "x1"; then
+        elif test "x$WINSSL_ENABLED" = "x1"; then
           versioned_symbols_flavour="WINSSL_"
-        elif test "x$DARWINSSL_ENABLED" == "x1"; then
+        elif test "x$DARWINSSL_ENABLED" = "x1"; then
           versioned_symbols_flavour="DARWINSSL_"
         else
           versioned_symbols_flavour=""
@@ -2613,8 +2502,10 @@ AC_MSG_RESULT(no)
 ]
 )
 
-AC_SUBST(VERSIONED_FLAVOUR, ["$versioned_symbols_flavour"])
+AC_SUBST([CURL_LT_SHLIB_VERSIONED_FLAVOUR],
-AM_CONDITIONAL(VERSIONED_SYMBOLS, test "x$versioned_symbols" = "xyes")
+  ["$versioned_symbols_flavour"])
+AM_CONDITIONAL([CURL_LT_SHLIB_USE_VERSIONED_SYMBOLS],
+  [test "x$versioned_symbols" = 'xyes'])
 
 dnl -------------------------------------------------
 dnl check winidn option before other IDN libraries
@@ -2812,7 +2703,7 @@ if test "$want_idn" = "yes"; then
     if test "x$ac_cv_header_tld_h" = "xyes"; then
       AC_SUBST([IDN_ENABLED], [1])
       curl_idn_msg="enabled"
-      if test -n "$IDN_DIR"; then
+      if test -n "$IDN_DIR" -a "x$cross_compiling" != "xyes"; then
         LD_LIBRARY_PATH="$LD_LIBRARY_PATH:$IDN_DIR"
         export LD_LIBRARY_PATH
         AC_MSG_NOTICE([Added $IDN_DIR to LD_LIBRARY_PATH])
@@ -2837,6 +2728,90 @@ dnl http://publibn.boulder.ibm.com/doc_link/en_US/a_doc_lib/aixprggd/ \
 dnl genprogc/thread_quick_ref.htm
 
 
+dnl **********************************************************************
+dnl Check for nghttp2
+dnl **********************************************************************
+
+AC_MSG_CHECKING([whether to build with nghttp2])
+OPT_H2="no"
+AC_ARG_WITH(nghttp2,
+AC_HELP_STRING([--with-nghttp2=PATH],[Enable nghttp2 usage])
+AC_HELP_STRING([--without-nghttp2],[Disable nghttp2 usage]),
+  [OPT_H2=$withval])
+case "$OPT_H2" in
+  no)
+    dnl --without-nghttp2 option used
+    want_h2="no"
+    AC_MSG_RESULT([no])
+    ;;
+  default)
+    dnl configure option not specified
+    want_h2="no"
+    AC_MSG_RESULT([no])
+    ;;
+  yes)
+    dnl --with-nghttp2 option used without path
+    want_h2="yes"
+    want_h2_path=""
+    AC_MSG_RESULT([yes])
+    ;;
+  *)
+    dnl --with-nghttp2 option used with path
+    want_h2="yes"
+    want_h2_path="$withval/lib/pkgconfig"
+    AC_MSG_RESULT([yes ($withval)])
+    ;;
+esac
+
+curl_h2_msg="disabled (--with-nghttp2)"
+if test X"$want_h2" != Xno; then
+  dnl backup the pre-nghttp2 variables
+  CLEANLDFLAGS="$LDFLAGS"
+  CLEANCPPFLAGS="$CPPFLAGS"
+  CLEANLIBS="$LIBS"
+
+  CURL_CHECK_PKGCONFIG(libnghttp2, $want_h2_path)
+
+  if test "$PKGCONFIG" != "no" ; then
+    LIB_H2=`CURL_EXPORT_PCDIR([$want_h2_path])
+      $PKGCONFIG --libs-only-l libnghttp2`
+    AC_MSG_NOTICE([-l is $LIB_H2])
+
+    CPP_H2=`CURL_EXPORT_PCDIR([$want_h2_path]) dnl
+      $PKGCONFIG --cflags-only-I libnghttp2`
+    AC_MSG_NOTICE([-I is $CPP_H2])
+
+    LD_H2=`CURL_EXPORT_PCDIR([$want_h2_path])
+      $PKGCONFIG --libs-only-L libnghttp2`
+    AC_MSG_NOTICE([-L is $LD_H2])
+
+  else
+    dnl To avoid link errors, we do not allow --libnghttp2 without
+    dnl a pkgconfig file
+    AC_MSG_ERROR([--with-nghttp2 was specified but could not find libnghttp2 pkg-config file.])
+  fi
+
+  LDFLAGS="$LDFLAGS $LD_H2"
+  CPPFLAGS="$CPPFLAGS $CPP_H2"
+  LIBS="$LIB_H2 $LIBS"
+
+  AC_CHECK_LIB(nghttp2, nghttp2_session_client_new,
+    [
+     AC_CHECK_HEADERS(nghttp2/nghttp2.h,
+        curl_h2_msg="enabled (nghttp2)"
+        NGHTTP2_ENABLED=1
+        AC_DEFINE(USE_NGHTTP2, 1, [if nghttp2 is in use])
+        AC_SUBST(USE_NGHTTP2, [1])
+     )
+    ],
+      dnl not found, revert back to clean variables
+      LDFLAGS=$CLEANLDFLAGS
+      CPPFLAGS=$CLEANCPPFLAGS
+      LIBS=$CLEANLIBS
+  )
+
+fi
+
 dnl **********************************************************************
 dnl Back to "normal" configuring
 dnl **********************************************************************
@@ -2997,7 +2972,6 @@ AC_TYPE_SIGNAL
 CURL_CHECK_FUNC_SELECT
 
 CURL_CHECK_FUNC_RECV
-CURL_CHECK_FUNC_RECVFROM
 CURL_CHECK_FUNC_SEND
 CURL_CHECK_MSG_NOSIGNAL
 
@@ -3039,12 +3013,10 @@ CURL_CHECK_FUNC_SIGSETJMP
 CURL_CHECK_FUNC_SOCKET
 CURL_CHECK_FUNC_SOCKETPAIR
 CURL_CHECK_FUNC_STRCASECMP
-CURL_CHECK_FUNC_STRCASESTR
 CURL_CHECK_FUNC_STRCMPI
 CURL_CHECK_FUNC_STRDUP
 CURL_CHECK_FUNC_STRERROR_R
 CURL_CHECK_FUNC_STRICMP
-CURL_CHECK_FUNC_STRLCAT
 CURL_CHECK_FUNC_STRNCASECMP
 CURL_CHECK_FUNC_STRNCMPI
 CURL_CHECK_FUNC_STRNICMP
@@ -3190,14 +3162,26 @@ if test "$want_thres" = "yes"; then
   AC_CHECK_HEADER(pthread.h,
     [ AC_DEFINE(HAVE_PTHREAD_H, 1, [if you have <pthread.h>])
       save_CFLAGS="$CFLAGS"
-      CFLAGS="$CFLAGS -pthread"
+
-      AC_CHECK_LIB(pthread, pthread_create,
+      dnl first check for function without lib
-        [ AC_MSG_NOTICE([using POSIX threaded DNS lookup])
+      AC_CHECK_FUNC(pthread_create, [USE_THREADS_POSIX=1] )
-          AC_DEFINE(USE_THREADS_POSIX, 1, [if you want POSIX threaded DNS lookup])
+
-          USE_THREADS_POSIX=1
+      dnl if it wasn't found without lib, search for it in pthread lib
-          curl_res_msg="threaded"
+      if test "$USE_THREADS_POSIX" != "1"
-        ],
+      then
-        [ CFLAGS="$save_CFLAGS"])
+        CFLAGS="$CFLAGS -pthread"
+        AC_CHECK_LIB(pthread, pthread_create,
+                     [USE_THREADS_POSIX=1],
+                     [ CFLAGS="$save_CFLAGS"])
+      fi
+
+      if test "x$USE_THREADS_POSIX" = "x1"
+      then
+        AC_DEFINE(USE_THREADS_POSIX, 1, [if you want POSIX threaded DNS lookup])
+        curl_res_msg="POSIX threaded"
+      fi
+
+
   ])
 fi
 
@@ -3267,6 +3251,7 @@ AC_HELP_STRING([--disable-crypto-auth],[Disable cryptographic authentication]),
   no)
        AC_MSG_RESULT(no)
        AC_DEFINE(CURL_DISABLE_CRYPTO_AUTH, 1, [to disable cryptographic authentication])
+       CURL_DISABLE_CRYPTO_AUTH=1
        ;;
   *)   AC_MSG_RESULT(yes)
        ;;
@@ -3370,6 +3355,11 @@ dnl yes or no
 ENABLE_SHARED="$enable_shared"
 AC_SUBST(ENABLE_SHARED)
 
+dnl to let curl-config output the static libraries correctly
+ENABLE_STATIC="$enable_static"
+AC_SUBST(ENABLE_STATIC)
+
+
 dnl
 dnl For keeping supported features and protocols also in pkg-config file
 dnl since it is more cross-compile friendly than curl-config
@@ -3380,9 +3370,6 @@ if test "x$USE_SSLEAY" = "x1"; then
 elif test -n "$SSL_ENABLED"; then
   SUPPORT_FEATURES="$SUPPORT_FEATURES SSL"
 fi
-if test "@KRB4_ENABLED@" = "x1"; then
-  SUPPORT_FEATURES="$SUPPORT_FEATURES KRB4"
-fi
 if test "x$IPV6_ENABLED" = "x1"; then
   SUPPORT_FEATURES="$SUPPORT_FEATURES IPv6"
 fi
@@ -3398,7 +3385,8 @@ fi
 if test "x$USE_WINDOWS_SSPI" = "x1"; then
   SUPPORT_FEATURES="$SUPPORT_FEATURES SSPI"
 fi
-if test "x$CURL_DISABLE_HTTP" != "x1"; then
+if test "x$CURL_DISABLE_HTTP" != "x1" -a \
+	"x$CURL_DISABLE_CRYPTO_AUTH" != "x1"; then
   if test "x$USE_SSLEAY" = "x1" -o "x$USE_WINDOWS_SSPI" = "x1" \
       -o "x$GNUTLS_ENABLED" = "x1" -o "x$NSS_ENABLED" = "x1" \
       -o "x$DARWINSSL_ENABLED" = "x1"; then
@@ -3412,6 +3400,16 @@ if test "x$USE_TLS_SRP" = "x1"; then
   SUPPORT_FEATURES="$SUPPORT_FEATURES TLS-SRP"
 fi
 
+if test "x$USE_NGHTTP2" = "x1"; then
+  SUPPORT_FEATURES="$SUPPORT_FEATURES HTTP2"
+fi
+if test "x$curl_spnego_msg" = "xenabled"; then
+  SUPPORT_FEATURES="$SUPPORT_FEATURES SPNEGO"
+fi
+if test "x$want_gss" = "xyes"; then
+  SUPPORT_FEATURES="$SUPPORT_FEATURES GSS-API"
+fi
+
 AC_SUBST(SUPPORT_FEATURES)
 
 dnl For supported protocols in pkg-config file
@@ -3546,6 +3544,8 @@ AC_OUTPUT
 
 CURL_GENERATE_CONFIGUREHELP_PM
 
+XC_AMEND_DISTCLEAN([lib src tests/unit tests/server tests/libtest docs/examples])
+
 AC_MSG_NOTICE([Configured to build curl/libcurl:
 
   curl version:     ${CURLVERSION}
@@ -3555,8 +3555,7 @@ AC_MSG_NOTICE([Configured to build curl/libcurl:
   SSL support:      ${curl_ssl_msg}
   SSH support:      ${curl_ssh_msg}
   zlib support:     ${curl_zlib_msg}
-  krb4 support:     ${curl_krb4_msg}
+  GSS-API support:  ${curl_gss_msg}
-  GSSAPI support:   ${curl_gss_msg}
   SPNEGO support:   ${curl_spnego_msg}
   TLS-SRP support:  ${curl_tls_srp_msg}
   resolver:         ${curl_res_msg}
@@ -3574,6 +3573,7 @@ AC_MSG_NOTICE([Configured to build curl/libcurl:
   RTSP support:     ${curl_rtsp_msg}
   RTMP support:     ${curl_rtmp_msg}
   metalink support: ${curl_mtlnk_msg}
+  HTTP2 support:    ${curl_h2_msg}
   Protocols:        ${SUPPORT_PROTOCOLS}
 ])
 

contributors.sh

@@ -0,0 +1,65 @@
+#!/bin/sh
+#***************************************************************************
+#                                  _   _ ____  _
+#  Project                     ___| | | |  _ \| |
+#                             / __| | | | |_) | |
+#                            | (__| |_| |  _ <| |___
+#                             \___|\___/|_| \_\_____|
+#
+# Copyright (C) 2013-2014, 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
+# are also available at http://curl.haxx.se/docs/copyright.html.
+#
+# You may opt to use, copy, modify, merge, publish, distribute and/or sell
+# copies of the Software, and permit persons to whom the Software is
+# furnished to do so, under the terms of the COPYING file.
+#
+# This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+# KIND, either express or implied.
+#
+###########################################################################
+
+#
+# This script shows all mentioned contributors from <hash> until HEAD. To aid
+# when writing RELEASE-NOTES and THANKS.
+#
+
+start=$1
+
+if test -z "$start"; then
+  echo "Usage: $0 <since this tag/hash>"
+fi
+
+# filter out Author:, Commit: and *by: lines
+# cut off the email parts
+# cut off spaces first and last on the line
+# only count names with a space (ie more than one word)
+# sort all unique names
+# awk them into RELEASE-NOTES format
+git log $start..HEAD | \
+egrep '(Author|Commit|by):' | \
+cut -d: -f2- | \
+cut '-d<' -f1 | \
+sed -e 's/^ //' -e 's/ $//g' | \
+grep ' ' | \
+sort -u |
+awk '{
+ num++;
+ n = sprintf("%s%s%s,", n, length(n)?" ":"", $0);
+ #print n;
+ if(length(n) > 78) {
+   printf("  %s\n", p);
+   n=sprintf("%s,", $0);
+ }
+ p=n;
+
+}
+
+ END {
+   printf("  %s\n", p);
+   printf("  (%d contributors)\n", num);
+ }
+
+'

curl-config.in

@@ -71,62 +71,62 @@ while test $# -gt 0; do
         ;;
 
     --ca)
-	echo "@CURL_CA_BUNDLE@"
+        echo "@CURL_CA_BUNDLE@"
-	;;
+        ;;
 
     --cc)
-	echo "@CC@"
+        echo "@CC@"
-	;;
+        ;;
 
     --prefix)
-	echo "$prefix"
+        echo "$prefix"
-	;;
+        ;;
 
     --feature|--features)
         for feature in @SUPPORT_FEATURES@ ""; do
             test -n "$feature" && echo "$feature"
         done
-	;;
+        ;;
 
     --protocols)
         for protocol in @SUPPORT_PROTOCOLS@; do
             echo "$protocol"
         done
-	;;
+        ;;
 
     --version)
-	echo libcurl @CURLVERSION@
+        echo libcurl @CURLVERSION@
-	exit 0
+        exit 0
-	;;
+        ;;
 
     --checkfor)
         checkfor=$2
         cmajor=`echo $checkfor | cut -d. -f1`
         cminor=`echo $checkfor | cut -d. -f2`
         # when extracting the patch part we strip off everything after a
-	# dash as that's used for things like version 1.2.3-CVS
+        # dash as that's used for things like version 1.2.3-CVS
-	cpatch=`echo $checkfor | cut -d. -f3 | cut -d- -f1`
+        cpatch=`echo $checkfor | cut -d. -f3 | cut -d- -f1`
         checknum=`echo "$cmajor*256*256 + $cminor*256 + ${cpatch:-0}" | bc`
         numuppercase=`echo @VERSIONNUM@ | tr 'a-f' 'A-F'`
         nownum=`echo "obase=10; ibase=16; $numuppercase" | bc`
 
-	if test "$nownum" -ge "$checknum"; then
+        if test "$nownum" -ge "$checknum"; then
-	  # silent success
+          # silent success
-	  exit 0
+          exit 0
-	else
+        else
-	  echo "requested version $checkfor is newer than existing @CURLVERSION@"
+          echo "requested version $checkfor is newer than existing @CURLVERSION@"
-	  exit 1
+          exit 1
-	fi
+        fi
-	;;
+        ;;
 
     --vernum)
-	echo @VERSIONNUM@
+        echo @VERSIONNUM@
-	exit 0
+        exit 0
-	;;
+        ;;
 
     --help)
-	usage 0
+        usage 0
-	;;
+        ;;
 
     --cflags)
         if test "X$cppflag_curl_staticlib" = "X-DCURL_STATICLIB"; then
@@ -134,38 +134,43 @@ while test $# -gt 0; do
         else
           CPPFLAG_CURL_STATICLIB=""
         fi
-       	if test "X@includedir@" = "X/usr/include"; then
+        if test "X@includedir@" = "X/usr/include"; then
           echo "$CPPFLAG_CURL_STATICLIB"
         else
           echo "${CPPFLAG_CURL_STATICLIB}-I@includedir@"
         fi
-       	;;
+        ;;
 
     --libs)
-	if test "X@libdir@" != "X/usr/lib" -a "X@libdir@" != "X/usr/lib64"; then
+        if test "X@libdir@" != "X/usr/lib" -a "X@libdir@" != "X/usr/lib64"; then
-	   CURLLIBDIR="-L@libdir@ "
+           CURLLIBDIR="-L@libdir@ "
-	else
+        else
-	   CURLLIBDIR=""
+           CURLLIBDIR=""
-	fi
+        fi
-	if test "X@REQUIRE_LIB_DEPS@" = "Xyes"; then
+        if test "X@REQUIRE_LIB_DEPS@" = "Xyes"; then
-	  echo ${CURLLIBDIR}-lcurl @LIBCURL_LIBS@
+          echo ${CURLLIBDIR}-lcurl @LIBCURL_LIBS@
-	else
+        else
-	  echo ${CURLLIBDIR}-lcurl
+          echo ${CURLLIBDIR}-lcurl
-	fi
+        fi
-	;;
+        ;;
 
     --static-libs)
-	echo @libdir@/libcurl.@libext@ @LDFLAGS@ @LIBCURL_LIBS@
+        if test "X@ENABLE_STATIC@" != "Xno" ; then
-	;;
+          echo @libdir@/libcurl.@libext@ @LDFLAGS@ @LIBCURL_LIBS@
+        else
+          echo "curl was built with static libraries disabled" >&2
+          exit 1
+        fi
+        ;;
 
     --configure)
-      echo @CONFIGURE_OPTIONS@
+        echo @CONFIGURE_OPTIONS@
-    ;;
+        ;;
 
     *)
         echo "unknown option: $1"
-	usage 1
+        usage 1
-	;;
+        ;;
     esac
     shift
 done

curl-style.el

@@ -1,50 +0,0 @@
-;;;; Emacs Lisp help for writing curl code. ;;;;
-
-;;; The curl hacker's C conventions.
-;;; See the sample.emacs file on how this file can be made to take
-;;; effect automatically when editing curl source files.
-
-(defconst curl-c-style
-  '((c-basic-offset . 2)
-    (c-comment-only-line-offset . 0)
-    (c-hanging-braces-alist     . ((substatement-open before after)))
-    (c-offsets-alist . ((topmost-intro        . 0)
-			(topmost-intro-cont   . 0)
-			(substatement         . +)
-			(substatement-open    . 0)
-			(statement-case-intro . +)
-			(statement-case-open  . 0)
-			(case-label           . 0)
-			))
-    )
-  "Curl C Programming Style")
-
-(defun curl-code-cleanup ()
-  "no docs"
-  (interactive)
-  (untabify (point-min) (point-max))
-  (delete-trailing-whitespace)
-)
-
-;; Customizations for all of c-mode, c++-mode, and objc-mode
-(defun curl-c-mode-common-hook ()
-  "Curl C mode hook"
-  ;; add curl style and set it for the current buffer
-  (c-add-style "curl" curl-c-style t)
-  (setq tab-width 8
-	indent-tabs-mode nil		; Use spaces. Not tabs.
-	comment-column 40
-	c-font-lock-extra-types (append '("bool" "CURL" "CURLcode" "ssize_t" "size_t" "curl_socklen_t" "fd_set" "time_t" "curl_off_t" "curl_socket_t" "in_addr_t" "CURLSHcode" "CURLMcode" "Curl_addrinfo"))
-	)
-  ;; keybindings for C, C++, and Objective-C.  We can put these in
-  ;; c-mode-base-map because of inheritance ...
-  (define-key c-mode-base-map "\M-q" 'c-fill-paragraph)
-  (define-key c-mode-base-map "\M-m" 'curl-code-cleanup)
-  (setq c-recognize-knr-p nil)
-  ;;; (add-hook 'write-file-hooks 'delete-trailing-whitespace t)
-  (setq show-trailing-whitespace t)
-  )
-
-;; Set this is in your .emacs if you want to use the c-mode-hook as
-;; defined here right out of the box.
-; (add-hook 'c-mode-common-hook 'curl-c-mode-common-hook)

docs/BINDINGS

@@ -6,14 +6,14 @@
 
                                libcurl bindings
 
-Creative people have written bindings or interfaces for various environments
+ Creative people have written bindings or interfaces for various environments
-and programming languages. Using one of these allows you to take advantage of
+ and programming languages. Using one of these allows you to take advantage of
-curl powers from within your favourite language or system.
+ curl powers from within your favourite language or system.
 
-This is a list of all known interfaces as of this writing.
+ This is a list of all known interfaces as of this writing.
 
-The bindings listed below are not part of the curl/libcurl distribution
+ The bindings listed below are not part of the curl/libcurl distribution
-archives, but must be downloaded and installed separately.
+ archives, but must be downloaded and installed separately.
 
 Ada95
 
@@ -41,7 +41,10 @@ Ch
 
 Cocoa
 
-  Written by Dan Wood
+  BBHTTP: written by Bruno de Carvalho
+  https://github.com/brunodecarvalho/BBHTTP
+
+  curlhandle: Written by Dan Wood
   http://curlhandle.sourceforge.net/
 
 D
@@ -55,6 +58,7 @@ Dylan
   http://dylanlibs.sourceforge.net/
 
 Eiffel
+
   Written by Eiffel Software
   http://curl.haxx.se/libcurl/eiffel/
 
@@ -81,6 +85,11 @@ glib/GTK+
   Written by Richard Atterer
   http://atterer.net/glibcurl/
 
+Guile:
+
+  Written by Michael L. Gran
+  http://www.lonelycactus.com/guile-curl.html
+
 Haskell
 
   Written by Galois, Inc
@@ -91,6 +100,11 @@ Java
   Maintained by [blank]
   http://curl.haxx.se/libcurl/java/
 
+Julia
+
+  Written by Paul Howe
+  https://github.com/forio/Curl.jl
+
 Lisp
 
   Written by Liam Healy

docs/CONTRIBUTE

@@ -79,9 +79,9 @@
 1.3 What To Read
 
  Source code, the man pages, the INTERNALS document, TODO, KNOWN_BUGS, the
- most recent CHANGES. Just lurking on the libcurl mailing list is gonna give
+ most recent CHANGES. Just lurking on the curl-library mailing list is gonna
- you a lot of insights on what's going on right now. Asking there is a good
+ give you a lot of insights on what's going on right now. Asking there is a
- idea too.
+ good idea too.
 
 2. cURL Coding Standards
 
@@ -98,12 +98,12 @@
 
 2.2 Indenting
 
- Please try using the same indenting levels and bracing method as all the
+ Use the same indenting levels and bracing method as all the other code
- other code already does. It makes the source code a lot easier to follow if
+ already does. It makes the source code easier to follow if all of it is
- all of it is written using the same style. We don't ask you to like it, we
+ written using the same style. We don't ask you to like it, we just ask you to
- just ask you to follow the tradition! ;-) This mainly means: 2-level indents,
+ follow the tradition! ;-) This mainly means: 2-level indents, using spaces
- using spaces only (no tabs) and having the opening brace ({) on the same line
+ only (no tabs) and having the opening brace ({) on the same line as the if()
- as the if() or while().
+ or while().
 
  Also note that we use if() and while() with no space before the parenthesis.
 
@@ -151,6 +151,9 @@
  description exactly what they correct so that all patches can be selectively
  applied by the maintainer or other interested parties.
 
+ Also, separate patches enable bisecting much better when we track problems in
+ the future.
+
 2.9 Patch Against Recent Sources
 
  Please try to get the latest available sources to make your patches
@@ -178,6 +181,10 @@
  test case that verifies that it works as documented. If every submitter also
  posts a few test cases, it won't end up as a heavy burden on a single person!
 
+ If you don't have test cases or perhaps you have done something that is very
+ hard to write tests for, do explain exactly how you have otherwise tested and
+ verified your changes.
+
 3. Pushing Out Your Changes
 
 3.1 Write Access to git Repository
@@ -212,7 +219,7 @@
  commit.
 
  Now send those patches off to the curl-library list. You can of course opt to
- do that with the 'get send-email' command.
+ do that with the 'git send-email' command.
 
 3.3 How To Make a Patch without git
 
@@ -271,6 +278,10 @@
       [full description, no wider than 72 columns that describe as much as
       possible as to why this change is made, and possibly what things
       it fixes and everything else that is related]
+
+      [Bug: link to source of the report or more related discussion]
+      [Reported-by: John Doe - credit the reporter]
+      [whatever-else-by: credit all helpers, finders, doers]
       ---- stop ----
 
  Don't forget to use commit --author="" if you commit someone else's work,

docs/DISTRO-DILEMMA

@@ -59,7 +59,7 @@ GnuTLS
  OpenSSL does. Now, you can build and distribute an TLS/SSL capable libcurl
  without including any Original BSD licensed code.
 
- I believe Debian is the first (only?) distro that provides libcurl/GnutTLS
+ I believe Debian is the first (only?) distro that provides libcurl/GnuTLS
  packages.
 
 yassl
@@ -72,20 +72,20 @@ GnuTLS vs OpenSSL vs yassl
 
  While these three libraries offer similar features, they are not equal.
  libcurl does not (yet) offer a standardized stable ABI if you decide to
- switch from using libcurl-openssl to libcurl-gnutls or vice versa. The GnuTLS
+ switch from using libcurl-openssl to libcurl-gnutls or vice-versa. The GnuTLS
  and yassl support is very recent in libcurl and it has not been tested nor
  used very extensively, while the OpenSSL equivalent code has been used and
  thus matured since 1999.
 
  GnuTLS
-   - LGPL licensened
+   - LGPL licensed
    - supports SRP
    - lacks SSLv2 support
    - lacks MD2 support (used by at least some CA certs)
    - lacks the crypto functions libcurl uses for NTLM
 
  OpenSSL
-   - Original BSD licensened
+   - Original BSD licensed
    - lacks SRP
    - supports SSLv2
    - older and more widely used

docs/FAQ

@@ -99,6 +99,7 @@ FAQ
   5.15 How do I get an FTP directory listing?
   5.16 I want a different time-out!
   5.17 Can I write a server with libcurl?
+  5.18 Does libcurl use threads?
 
  6. License Issues
   6.1 I have a GPL program, can I use the libcurl library?
@@ -202,27 +203,25 @@ FAQ
   better. We do however believe in a few rules when it comes to the future of
   curl:
 
-  * Curl -- the command line tool -- is to remain a non-graphical command line
+  Curl -- the command line tool -- is to remain a non-graphical command line
-    tool. If you want GUIs or fancy scripting capabilities, you should look
+  tool. If you want GUIs or fancy scripting capabilities, you should look for
-    for another tool that uses libcurl.
+  another tool that uses libcurl.
 
-  * We do not add things to curl that other small and available tools already
+  We do not add things to curl that other small and available tools already do
-    do very fine at the side. Curl's output is fine to pipe into another
+  very fine at the side. Curl's output is fine to pipe into another program or
-    program or redirect to another file for the next program to interpret.
+  redirect to another file for the next program to interpret.
 
-  * We focus on protocol related issues and improvements. If you wanna do more
+  We focus on protocol related issues and improvements. If you wanna do more
-    magic with the supported protocols than curl currently does, chances are
+  magic with the supported protocols than curl currently does, chances are big
-    big we will agree. If you wanna add more protocols, we may very well
+  we will agree. If you wanna add more protocols, we may very well agree.
-    agree.
 
-  * If you want someone else to make all the work while you wait for us to
+  If you want someone else to make all the work while you wait for us to
-    implement it for you, that is not a very friendly attitude. We spend a
+  implement it for you, that is not a very friendly attitude. We spend a
-    considerable time already on maintaining and developing curl. In order to
+  considerable time already on maintaining and developing curl. In order to
-    get more out of us, you should consider trading in some of your time and
+  get more out of us, you should consider trading in some of your time and
-    efforts in return.
+  efforts in return.
 
-  * If you write the code, chances are bigger that it will get into curl
+  If you write the code, chances are bigger that it will get into curl faster.
-    faster.
 
   1.5 Who makes curl?
 
@@ -245,10 +244,10 @@ FAQ
   supervised in any way by the project.
 
   We still get help from companies. Haxx provides web site, bandwidth, mailing
-  lists etc and sourceforge.net hosts project services we take advantage from,
+  lists etc, sourceforge.net hosts project services we take advantage from,
-  like the bug tracker. Also again, some companies have sponsored certain
+  like the bug tracker and github hosts the primary git repository. Also
-  parts of the development in the past and I hope some will continue to do so
+  again, some companies have sponsored certain parts of the development in the
-  in the future.
+  past and I hope some will continue to do so in the future.
 
   If you want to support our project, consider a donation or a banner-program
   or even better: by helping us coding, documenting, testing etc.
@@ -263,7 +262,7 @@ FAQ
 
   Our project name curl has been in effective use since 1998. We were not the
   first computer related project to use the name "curl" and do not claim any
-  first-hand rights to the name.
+  rights to the name.
 
   We recognize that we will be living in parallel with curl.com and wish them
   every success.
@@ -309,17 +308,16 @@ FAQ
   never use it.
 
   In May 2012 Daniel did a counting game and came up with a number that may
-  be completely wrong or somewhat accurate. 300 million!
+  be completely wrong or somewhat accurate. Over 500 million!
 
   See http://daniel.haxx.se/blog/2012/05/16/300m-users/
 
   1.11 Why don't you update ca-bundle.crt
 
-  The ca-bundle.crt file that used to be bundled with curl was very outdated
+  The ca cert bundle that used to shipped with curl was very outdated and must
-  (it being last modified year 2000 should tell) and must be replaced with a
+  be replaced with an up-to-date version by anyone who wants to verify
-  much more modern and up-to-date version by anyone who wants to verify peers
+  peers. It is no longer provided by curl. The last curl release ever that
-  anyway. It is no longer provided, the last curl release that shipped it was
+  shipped a ca cert bundle was curl 7.18.0.
-  curl 7.18.0.
 
   In the cURL project we've decided not to attempt to keep this file updated
   (or even present anymore) since deciding what to add to a ca cert bundle is
@@ -425,7 +423,7 @@ FAQ
 
   curl can be built to use one of the following SSL alternatives: OpenSSL,
   GnuTLS, yassl, NSS, PolarSSL, axTLS, Secure Transport (native iOS/OS X),
-  schannel (native Windows) or qssl (native IBM i). They all have their pros
+  WinSSL (native Windows) or qssl (native IBM i). They all have their pros
   and cons, and we try to maintain a comparison of them here:
   http://curl.haxx.se/docs/ssl-compared.html
 
@@ -433,10 +431,10 @@ FAQ
 
   That is an OpenSSL binary built for Windows.
 
-  Curl uses OpenSSL to do the SSL stuff. The LIBEAY32.DLL is what curl needs
+  Curl can be built with OpenSSL to do the SSL stuff. The LIBEAY32.DLL is then
-  on a windows machine to do https://. Check out the curl web site to find
+  what curl needs on a windows machine to do https:// etc. Check out the curl
-  accurate and up-to-date pointers to recent OpenSSL DLLs and other binary
+  web site to find accurate and up-to-date pointers to recent OpenSSL DLLs and
-  packages.
+  other binary packages.
 
   2.4 Does curl support SOCKS (RFC 1928) ?
 
@@ -472,9 +470,9 @@ FAQ
   3.3 Why doesn't my posting using -F work?
 
   You can't simply use -F or -d at your choice. The web server that will
-  receive your post assumes one of the formats. If the form you're trying to
+  receive your post expects one of the formats. If the form you're trying to
-  "fake" sets the type to 'multipart/form-data', then and only then you must
+  submit uses the type 'multipart/form-data', then and only then you must use
-  use the -F type. In all the most common cases, you should use -d which then
+  the -F type. In all the most common cases, you should use -d which then
   causes a posting with the type 'application/x-www-form-urlencoded'.
 
   This is described in some detail in the MANUAL and TheArtOfHttpScripting
@@ -502,9 +500,9 @@ FAQ
   3.6 Does curl support ASP, XML, XHTML or HTML version Y?
 
   To curl, all contents are alike. It doesn't matter how the page was
-  generated. It may be ASP, PHP, Perl, shell-script, SSI or plain
+  generated. It may be ASP, PHP, Perl, shell-script, SSI or plain HTML
-  HTML-files. There's no difference to curl and it doesn't even know what kind
+  files. There's no difference to curl and it doesn't even know what kind of
-  of language that generated the page.
+  language that generated the page.
 
   See also item 3.14 regarding javascript.
 
@@ -621,15 +619,15 @@ FAQ
 
   Some workarounds usually suggested to overcome this Javascript dependency:
 
-  - Depending on the Javascript complexity, write up a script that
+  Depending on the Javascript complexity, write up a script that translates it
-    translates it to another language and execute that.
+  to another language and execute that.
 
-  - Read the Javascript code and rewrite the same logic in another language.
+  Read the Javascript code and rewrite the same logic in another language.
 
-  - Implement a Javascript interpreter, people have successfully used the
+  Implement a Javascript interpreter, people have successfully used the
-    Mozilla Javascript engine in the past.
+  Mozilla Javascript engine in the past.
 
-  - Ask your admins to stop this, for a static proxy setup or similar.
+  Ask your admins to stop this, for a static proxy setup or similar.
 
   3.15 Can I do recursive fetches with curl?
 
@@ -645,34 +643,38 @@ FAQ
   There are three different kinds of "certificates" to keep track of when we
   talk about using SSL-based protocols (HTTPS or FTPS) using curl or libcurl.
 
-  - Client certificate. The server you communicate may require that you can
+  CLIENT CERTIFICATE
-    provide this in order to prove that you actually are who you claim to be.
-    If the server doesn't require this, you don't need a client certificate.
 
-    A client certificate is always used together with a private key, and the
+  The server you communicate may require that you can provide this in order to
-    private key has a pass phrase that protects it.
+  prove that you actually are who you claim to be.  If the server doesn't
+  require this, you don't need a client certificate.
 
-  - Server certificate. The server you communicate with has a server
+  A client certificate is always used together with a private key, and the
-    certificate. You can and should verify this certificate to make sure that
+  private key has a pass phrase that protects it.
-    you are truly talking to the real server and not a server impersonating
-    it.
 
-  - Certificate Authority certificate ("CA cert"). You often have several CA
+  SERVER CERTIFICATE
-    certs in a CA cert bundle that can be used to verify a server certificate
-    that was signed by one of the authorities in the bundle. curl does not
-    come with a CA cert bundle but most curl installs provide one. You can
-    also override the default.
 
-    The server certificate verification process is made by using a Certificate
+  The server you communicate with has a server certificate. You can and should
-    Authority certificate ("CA cert") that was used to sign the server
+  verify this certificate to make sure that you are truly talking to the real
-    certificate. Server certificate verification is enabled by default in curl
+  server and not a server impersonating it.
-    and libcurl and is often the reason for problems as explained in FAQ entry
+
-    4.12 and the SSLCERTS document
+  CERTIFICATE AUTHORITY CERTIFICATE ("CA cert")
-    (http://curl.haxx.se/docs/sslcerts.html). Server certificates that are
+
-    "self-signed" or otherwise signed by a CA that you do not have a CA cert
+  You often have several CA certs in a CA cert bundle that can be used to
-    for, cannot be verified. If the verification during a connect fails, you
+  verify a server certificate that was signed by one of the authorities in the
-    are refused access. You then need to explicitly disable the verification
+  bundle. curl does not come with a CA cert bundle but most curl installs
-    to connect to the server.
+  provide one. You can also override the default.
+
+  The server certificate verification process is made by using a Certificate
+  Authority certificate ("CA cert") that was used to sign the server
+  certificate. Server certificate verification is enabled by default in curl
+  and libcurl and is often the reason for problems as explained in FAQ entry
+  4.12 and the SSLCERTS document
+  (http://curl.haxx.se/docs/sslcerts.html). Server certificates that are
+  "self-signed" or otherwise signed by a CA that you do not have a CA cert
+  for, cannot be verified. If the verification during a connect fails, you are
+  refused access. You then need to explicitly disable the verification to
+  connect to the server.
 
   3.17 How do I list the root dir of an FTP server?
 
@@ -729,7 +731,7 @@ FAQ
   When passing on a URL to curl to use, it may respond that the particular
   protocol is not supported or disabled. The particular way this error message
   is phrased is because curl doesn't make a distinction internally of whether
-  a particular protocol is not supported (ie never got any code added that
+  a particular protocol is not supported (i.e. never got any code added that
   knows how to speak that protocol) or if it was explicitly disabled. curl can
   be built to only support a given set of protocols, and the rest would then
   be disabled or not supported.
@@ -795,12 +797,13 @@ FAQ
 
      curl 'http://www.altavista.com/cgi-bin/query?text=yes&q=curl'
 
-  In Windows, the standard DOS shell treats the %-symbol specially and you
+  In Windows, the standard DOS shell treats the percent sign specially and you
-  need to use TWO %-symbols for each single one you want to use in the URL.
+  need to use TWO percent signs for each single one you want to use in the
+  URL.
 
-  Also note that if you want the literal %-symbol to be part of the data you
+  If you want a literal percent sign to be part of the data you pass in a POST
-  pass in a POST using -d/--data you must encode it as '%25' (which then also
+  using -d/--data you must encode it as '%25' (which then also needs the
-  needs the %-symbol doubled on Windows machines).
+  percent sign doubled on Windows machines).
 
   4.3 How can I use {, }, [ or ] to specify multiple URLs?
 
@@ -969,13 +972,13 @@ FAQ
   4.14 Redirects work in browser but not with curl!
 
   curl supports HTTP redirects fine (see item 3.8). Browsers generally support
-  at least two other ways to perform directs that curl does not:
+  at least two other ways to perform redirects that curl does not:
 
-  - Meta tags. You can write a HTML tag that will cause the browser to
+  Meta tags. You can write a HTML tag that will cause the browser to redirect
-    redirect to another given URL after a certain time.
+  to another given URL after a certain time.
 
-  - Javascript. You can write a Javascript program embedded in a HTML page
+  Javascript. You can write a Javascript program embedded in a HTML page that
-    that redirects the browser to another given URL.
+  redirects the browser to another given URL.
 
   There is no way to make curl follow these redirects. You must either
   manually figure out what the page is set to do, or you write a script that
@@ -1056,11 +1059,11 @@ FAQ
 
   4.19 Why doesn't cURL return an error when the network cable is unplugged?
 
-  Unplugging the cable is not an error situation. The TCP/IP protocol stack
+  Unplugging a cable is not an error situation. The TCP/IP protocol stack
   was designed to be fault tolerant, so even though there may be a physical
   break somewhere the connection shouldn't be affected, just possibly
   delayed.  Eventually, the physical break will be fixed or the data will be
-  re-routed around the physical problem.
+  re-routed around the physical problem through another path.
 
   In such cases, the TCP/IP stack is responsible for detecting when the
   network connection is irrevocably lost. Since with some protocols it is
@@ -1078,6 +1081,12 @@ FAQ
   falls too low, and --connect-timeout and --max-time can be used to put an
   overall timeout on the connection phase or the entire transfer.
 
+  A libcurl-using application running in a known physical environment (e.g.
+  an embedded device with only a single network connection) may want to act
+  immediately if its lone network connection goes down.  That can be achieved
+  by having the application monitor the network connection on its own using an
+  OS-specific mechanism, then signalling libcurl to abort (see also item 5.13).
+  
 
 5. libcurl Issues
 
@@ -1087,7 +1096,9 @@ FAQ
 
   We have written the libcurl code specifically adjusted for multi-threaded
   programs. libcurl will use thread-safe functions instead of non-safe ones if
-  your system has such.
+  your system has such.  Note that you must never share the same handle in
+  multiple threads.
+
 
   If you use a OpenSSL-powered libcurl in a multi-threaded environment, you
   need to provide one or two locking functions:
@@ -1263,17 +1274,18 @@ FAQ
 
   5.12 Can I make libcurl fake or hide my real IP address?
 
-  No. libcurl operates on a higher level than so. Besides, faking IP address
+  No. libcurl operates on a higher level. Besides, faking IP address would
-  would imply sending IP packages with a made-up source address, and then you
+  imply sending IP packet with a made-up source address, and then you normally
-  normally get a problem with intercepting the packages sent back as they
+  get a problem with receiving the packet sent back as they would then not be
-  would then not be routed to you!
+  routed to you!
 
   If you use a proxy to access remote sites, the sites will not see your local
   IP address but instead the address of the proxy.
 
   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.
+  remote server will see you coming from. You may also consider using
+  http://www.torproject.org .
 
   5.13 How do I stop an ongoing transfer?
 
@@ -1354,6 +1366,19 @@ FAQ
   server for. And there are really good stand-alone ones that have been tested
   and proven for many years. There's no need for you to reinvent them!
 
+  5.18 Does libcurl use threads?
+
+  Put simply: no, libcurl will execute in the same thread you call it in. All
+  callbacks will be called in the same thread as the one you call libcurl in.
+
+  If you want to avoid your thread to be blocked by the libcurl call, you make
+  sure you use the non-blocking API which will do transfers asynchronously -
+  but still in the same single thread.
+
+  libcurl will potentially internally use threads for name resolving, if it
+  was built to work like that, but in those cases it'll create the child
+  threads by itself and they will only be used and then killed internally by
+  libcurl and never exposed to the outside.
 
 6. License Issues
 

docs/FEATURES

@@ -13,27 +13,29 @@ curl tool
  - multiple file upload on a single command line
  - custom maximum transfer rate
  - redirectable stderr
+ - metalink support (*13)
 
-libcurl supports
+libcurl
  - full URL syntax with no length limit
  - custom maximum download time
  - custom least download speed acceptable
  - custom output result after completion
  - guesses protocol from host name unless specified
  - uses .netrc
- - progress bar/time specs while downloading
+ - progress bar with time statistics while downloading
  - "standard" proxy environment variables support
  - compiles on win32 (reported builds on 40+ operating systems)
  - selectable network interface for outgoing traffic
  - IPv6 support on unix and Windows
  - persistent connections
  - socks5 support
- - supports user name + password in proxy environment variables
+ - supports user name and password in proxy environment variables
  - operations through proxy "tunnel" (using CONNECT)
- - supports large files (>2GB and >4GB) both upload/download
+ - support for large files (>2GB and >4GB) during upload and download
  - replaceable memory functions (malloc, free, realloc, etc)
  - asynchronous name resolving (*6)
  - both a push and a pull style interface
+ - international domain names (*11)
 
 HTTP
  - HTTP/1.1 compliant (optionally uses 1.0)
@@ -53,14 +55,15 @@ HTTP
  - reads/writes the netscape cookie file format
  - custom headers (replace/remove internally generated headers)
  - custom user-agent string
- - custom referer string
+ - custom referrer string
  - range
  - proxy authentication
  - time conditions
  - via http-proxy
  - retrieve file modification date
  - Content-Encoding support for deflate and gzip
- - "Transfer-Encoding: chunked" support for "uploads"
+ - "Transfer-Encoding: chunked" support in uploads
+ - data compression (*12)
 
 HTTPS (*1)
  - (all the HTTP features)
@@ -68,12 +71,13 @@ HTTPS (*1)
  - verify server certificate
  - via http-proxy
  - select desired encryption
- - force usage of a specific SSL version (SSLv2(*7), SSLv3 or TLSv1)
+ - force usage of a specific SSL version (SSLv2 (*7), SSLv3 (*10) or TLSv1)
 
 FTP
  - download
  - authentication
- - kerberos4 (*5), kerberos5 (*3)
+ - kerberos4 (*5)
+ - kerberos5 (*3)
  - active/passive using PORT, EPRT, PASV or EPSV
  - single file size information (compare to HTTP HEAD)
  - 'type=' URL support
@@ -93,7 +97,7 @@ FTP
 
 FTPS (*1)
  - implicit ftps:// support that use SSL on both connections
- - explicit "AUTH TSL" and "AUTH SSL" usage to "upgrade" plain ftp://
+ - explicit "AUTH TLS" and "AUTH SSL" usage to "upgrade" plain ftp://
    connection to use SSL for both or one of the connections
 
 SCP (*8)
@@ -104,7 +108,8 @@ SFTP (*8)
  - with custom commands sent before/after the transfer
 
 TFTP
- - download / upload
+ - download
+ - upload
 
 TELNET
  - connection negotiation
@@ -119,12 +124,12 @@ DICT
 
 FILE
  - URL support
- - "uploads"
+ - upload
  - resume
 
 SMTP
  - authentication: Plain, Login, CRAM-MD5, Digest-MD5 and NTLM (*9)
- - send mail
+ - send e-mails
  - mail from support
  - mail size support
  - mail auth support for trusted server-to-server relaying
@@ -142,7 +147,8 @@ POP3
    NTLM (*9)
  - list e-mails
  - retrieve e-mails
- - enhanced command support for: CAPA, DELE, TOP, STAT, UIDL and NOOP
+ - enhanced command support for: CAPA, DELE, TOP, STAT, UIDL and NOOP via
+   custom requests
  - via http-proxy
 
 POP3S (*1)
@@ -152,10 +158,14 @@ POP3S (*1)
 
 IMAP
  - authentication: Clear Text and SASL
- - select mailbox
- - basic fetch e-mail support
  - SASL based authentication: Plain, Login, CRAM-MD5, Digest-MD5 and
    NTLM (*9)
+ - list the folders of a mailbox
+ - select a mailbox with support for verifying the UIDVALIDITY
+ - fetch e-mails with support for specifying the UID and SECTION
+ - upload e-mails via the append command
+ - enhanced command support for: EXAMINE, CREATE, DELETE, RENAME, STATUS,
+   STORE, COPY and UID via custom requests
  - via http-proxy
 
 IMAPS (*1)
@@ -166,13 +176,21 @@ IMAPS (*1)
 FOOTNOTES
 =========
 
-  *1 = requires OpenSSL, GnuTLS, NSS, yassl, axTLS, PolarSSL, schannel (native
+  *1 = requires OpenSSL, GnuTLS, NSS, yassl, axTLS, PolarSSL, WinSSL (native
-       Windows), Secure Transport (native iOS/OS X)  or qssl (native IBM i)
+       Windows), Secure Transport (native iOS/OS X) or qssl (native IBM i)
   *2 = requires OpenLDAP
-  *3 = requires a GSSAPI-compliant library, such as Heimdal or similar.
+  *3 = requires a GSSAPI-compliant library, such as Heimdal or similar
   *4 = requires FBopenssl
-  *5 = requires a krb4 library, such as the MIT one or similar.
+  *5 = requires a krb4 library, such as the MIT one or similar
   *6 = requires c-ares
-  *7 = requires OpenSSL or NSS, as GnuTLS only supports SSLv3 and TLSv1
+  *7 = requires OpenSSL, NSS, qssl, WinSSL or Secure Transport; GnuTLS, for
+       example, only supports SSLv3 and TLSv1
   *8 = requires libssh2
-  *9 = requires OpenSSL, GnuTLS, NSS, yassl or SSPI (native Windows)
+  *9 = requires OpenSSL, GnuTLS, NSS, yassl, Secure Transport or SSPI (native
+       Windows)
+  *10 = requires any of the SSL libraries in (*1) above other than axTLS, which
+        does not support SSLv3
+  *11 = requires libidn or Windows
+  *12 = requires libz
+  *13 = requires libmetalink, and either an Apple or Microsoft operating
+        system, or OpenSSL, or GnuTLS, or NSS

docs/HISTORY

@@ -7,19 +7,19 @@
                           How cURL Became Like This
 
 
-In the second half of 1997, Daniel Stenberg came up with the idea to make
+Towards the end of 1996, Daniel Stenberg came up with the idea to make
 currency-exchange calculations available to Internet Relay Chat (IRC)
 users. All the necessary data are published on the Web; he just needed to
 automate their retrieval.
 
 Daniel simply adopted an existing command-line open-source tool, httpget, that
-Brazilian Rafael Sagula had written. After a few minor adjustments, it did
+Brazilian Rafael Sagula had written and recently release version 0.1 of. After
-just what he needed.
+a few minor adjustments, it did just what he needed. HttpGet 1.0 was released
+on April 8th 1997 with brand new HTTP proxy support.
 
-Soon, he found currencies on a GOPHER site, so support for that had to go in,
+We soon found and fixed support for getting currencies over GOPHER.  Once FTP
-and not before long FTP download support was added as well. The name of the
+download support was added, the name of the project was changed and urlget 2.0
-project was changed to urlget to better fit what it actually did now, since
+was released in August 1997. The http-only days were already passed.
-the http-only days were already passed.
 
 The project slowly grew bigger. When upload capabilities were added and the
 name once again was misleading, a second name change was made and on March 20,

docs/INSTALL

@@ -115,18 +115,6 @@ UNIX
 
        ./configure --disable-thread
 
-     To build curl with kerberos4 support enabled, curl requires the krb4 libs
-     and headers installed. You can then use a set of options to tell
-     configure where those are:
-
-          --with-krb4-includes[=DIR]   Specify location of kerberos4 headers
-          --with-krb4-libs[=DIR]       Specify location of kerberos4 libs
-          --with-krb4[=DIR]            where to look for Kerberos4
-
-     In most cases, /usr/athena is the install prefix and then it works with
-
-       ./configure --with-krb4=/usr/athena
-
      If you're a curl developer and use gcc, you might want to enable more
      debug options with the --enable-debug option.
 
@@ -220,8 +208,8 @@ Win32
    adjust as necessary. It is also possible to override these paths with
    environment variables, for example:
 
-     set ZLIB_PATH=c:\zlib-1.2.7
+     set ZLIB_PATH=c:\zlib-1.2.8
-     set OPENSSL_PATH=c:\openssl-0.9.8x
+     set OPENSSL_PATH=c:\openssl-0.9.8y
      set LIBSSH2_PATH=c:\libssh2-1.4.3
 
    ATTENTION: if you want to build with libssh2 support you have to use latest
@@ -264,8 +252,10 @@ Win32
    MSVC 6 caveats
    --------------
 
-   If you use MSVC 6 it is required that you use the February 2003 edition PSDK:
+   If you use MSVC 6 it is required that you use the February 2003 edition of
-   http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm
+   the 'Platform SDK' which can be downloaded from:
+
+   http://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
@@ -273,8 +263,6 @@ Win32
    choice of static vs dynamic runtime and third party libraries. Anyone using
    software built in such way will at some point regret having done so.
 
-   When someone uses MSVC 6 without PSDK he is using a compiler back from 1998.
-
    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
    safely used to read source code, translate and make it object code.
@@ -284,13 +272,6 @@ Win32
    header files and libraries with bugs and security issues which have already
    been addressed and fixed long time ago.
 
-   In order to make use of the updated system headers and fixed libraries
-   for MSVC 6, it is required that 'Platform SDK', PSDK from now onwards,
-   is installed. The specific PSDK that must be installed for MSVC 6 is the
-   February 2003 edition, which is the latest one supporting the MSVC 6 compiler,
-   this PSDK is also known as 'Windows Server 2003 PSDK' and can be downloaded
-   from http://www.microsoft.com/msdownload/platformsdk/sdkupdate/psdk-full.htm
-
    So, building curl and libcurl with MSVC 6 without PSDK is absolutely
    discouraged for the benefit of anyone using software built in such
    environment. And it will not be supported in any way, as we could just
@@ -323,7 +304,7 @@ Win32
    documentation on how to compile zlib. Define the ZLIB_PATH environment
    variable to the location of zlib.h and zlib.lib, for example:
 
-     set ZLIB_PATH=c:\zlib-1.2.7
+     set ZLIB_PATH=c:\zlib-1.2.8
 
    Then run 'nmake vc-zlib' in curl's root directory.
 
@@ -337,7 +318,7 @@ Win32
    Before running nmake define the OPENSSL_PATH environment variable with
    the root/base directory of OpenSSL, for example:
 
-     set OPENSSL_PATH=c:\openssl-0.9.8x
+     set OPENSSL_PATH=c:\openssl-0.9.8y
 
    Then run 'nmake vc-ssl' or 'nmake vc-ssl-dll' in curl's root
    directory.  'nmake vc-ssl' will create a libcurl static and dynamic
@@ -352,39 +333,18 @@ Win32
    at runtime.
    Run 'nmake vc-ssl-zlib' to build with both ssl and zlib support.
 
-   MSVC 6 IDE
+   MSVC IDE
-   ----------
+   --------
 
-   A minimal VC++ 6.0 reference workspace (vc6curl.dsw) is available with the
+   A fairly comprehensive set of Visual Studio project files are available for
-   source distribution archive to allow proper building of the two included
+   v6.0 through v12.0 and are located in the projects folder to allow proper
-   projects, the libcurl library and the curl tool.
+   building of both the libcurl library as well as the curl tool.
 
-   1) Open the vc6curl.dsw workspace with MSVC6's IDE.
+   For more information about these projects and building via Visual Studio
-   2) Select 'Build' from top menu.
+   please see the README file located in the projects folder.
-   3) Select 'Batch Build' from dropdown menu.
-   4) Make sure that the eight project configurations are 'checked'.
-   5) Click on the 'Build' button.
-   6) Once the eight project configurations are built you are done.
-
-   Dynamic and static libcurl libraries are built in debug and release flavours,
-   and can be located each one in its own subdirectory, DLL-Debug, DLL-Release,
-   LIB-Debug and LIB-Release, all of them below the 'lib' subdirectory.
-
-   In the same way four curl executables are created, each using its respective
-   library. The resulting curl executables are located in its own subdirectory,
-   DLL-Debug, DLL-Release, LIB-Debug and LIB-Release, below the 'src' subdir.
-
-   These reference VC++ 6.0 configurations are generated using the dynamic CRT.
-
-   Intentionally, these reference VC++ 6.0 projects and configurations don't use
-   third party libraries, such as OpenSSL or Zlib, to allow proper compilation
-   and configuration for all new users without further requirements.
-
-   If you need something more 'involved' you might adjust them for your own use,
-   or explore the world of makefiles described above 'MSVC from command line'.
 
    Borland C++ compiler
-   ---------------------
+   --------------------
 
    Ensure that your build environment is properly set up to use the compiler
    and associated tools. PATH environment variable must include the path to
@@ -876,7 +836,7 @@ VxWorks
 Android
 =======
    Method using the static makefile:
-      - see the build notes in the Android.mk file.
+      - see the build notes in the packages/Android/Android.mk file.
 
    Method using a configure cross-compile (tested with Android NDK r7c, r8):
       - prepare the toolchain of the Android NDK for standalone use; this can
@@ -993,6 +953,7 @@ REDUCING SIZE
      --disable-verbose (eliminates debugging strings and error code strings)
      --enable-hidden-symbols (eliminates unneeded symbols in the shared library)
      --without-libidn (disables support for the libidn DNS library)
+     --without-librtmp (disables support for RTMP)
      --without-ssl (disables support for SSL/TLS)
      --without-zlib (disables support for on-the-fly decompression)
 
@@ -1011,9 +972,9 @@ REDUCING SIZE
    .comment section).
 
    Using these techniques it is possible to create a basic HTTP-only shared
-   libcurl library for i386 Linux platforms that is only 106 KiB in size, and
+   libcurl library for i386 Linux platforms that is only 114 KiB in size, and
-   an FTP-only library that is 108 KiB in size (as of libcurl version 7.27.0,
+   an FTP-only library that is 115 KiB in size (as of libcurl version 7.35.0,
-   using gcc 4.6.3).
+   using gcc 4.8.2).
 
    You may find that statically linking libcurl to your application will
    result in a lower total size than dynamically linking.
@@ -1025,7 +986,6 @@ REDUCING SIZE
    command line.  Following is a list of appropriate key words:
 
      --disable-cookies          !cookies
-     --disable-crypto-auth      !HTTP\ Digest\ auth !HTTP\ proxy\ Digest\ auth
      --disable-manual           !--manual
      --disable-proxy            !HTTP\ proxy !proxytunnel !SOCKS4 !SOCKS5
 
@@ -1045,7 +1005,7 @@ PORTS
         - Alpha OpenVMS V7.1-1H2
         - Alpha Tru64 v5.0 5.1
         - AVR32 Linux
-        - ARM Android 1.5, 2.1
+        - ARM Android 1.5, 2.1, 2.3, 3.2, 4.x
         - ARM INTEGRITY
         - ARM iOS
         - Cell Linux
@@ -1116,6 +1076,7 @@ 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/
+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/

docs/INSTALL.cmake

@@ -71,7 +71,7 @@ Command Line CMake
 
     $ make install
 
-    (The teste suit does not work with the cmake build)
+    (The test suite does not work with the cmake build)
 
 ccmake
 =========

docs/INTERNALS

@@ -42,9 +42,10 @@ Portability
  cyassl       2.0.0
  openldap     2.0
  MIT krb5 lib 1.2.4
- qsossl       V5R2M0
+ qsossl       V5R3M0
- NSS          3.12.x
+ NSS          3.14.x
  axTLS        1.2.7
+ PolarSSL     1.3.0
  Heimdal      ?
 
  On systems where configure runs, we aim at working on them all - if they have
@@ -52,7 +53,7 @@ Portability
  curl running fine on:
 
  Windows      98
- AS/400       V5R2M0
+ AS/400       V5R3M0
  Symbian      9.1
  Windows CE   ?
  TPF          ?
@@ -111,6 +112,9 @@ Windows vs Unix
 Library
 =======
 
+ (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
@@ -135,16 +139,18 @@ Library
  options is documented in the man page. This function mainly sets things in
  the 'SessionHandle' struct.
 
- curl_easy_perform() does a whole lot of things:
+ 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.
 
- It starts off in the lib/easy.c file by calling Curl_perform() and the main
+ Some of the most important key functions in url.c are called from multi.c
- work then continues in lib/url.c. The flow continues with a call to
+ when certain key steps are to be made in the transfer operation.
- Curl_connect() to connect to the remote site.
 
  o Curl_connect()
 
-   ... analyzes the URL, it separates the different components and connects to
+   Analyzes the URL, it separates the different components and connects to the
-   the remote host. This may involve using a proxy and/or using SSL. 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
    (it does then use the proper underlying method, which may vary between
    platforms and builds).
@@ -160,10 +166,7 @@ Library
  o Curl_do()
 
    Curl_do() makes sure the proper protocol-specific function is called. The
-   functions are named after the protocols they handle. Curl_ftp(),
+   functions are named after the protocols they handle.
-   Curl_http(), Curl_dict(), etc. They all reside in their respective files
-   (ftp.c, http.c and dict.c). HTTPS is handled by Curl_http() and FTPS by
-   Curl_ftp().
 
    The protocol-specific functions of course deal with protocol-specific
    negotiations and setup. They have access to the Curl_sendf() (from
@@ -182,10 +185,9 @@ Library
    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 Transfer()
+ o Curl_readwrite()
 
-   Curl_perform() then calls Transfer() in lib/transfer.c that performs the
+   Called during the transfer of the actual protocol payload.
-   entire file transfer.
 
    During transfer, the progress functions in lib/progress.c are called at a
    frequent interval (or at the user's choice, a specified callback might get
@@ -207,33 +209,11 @@ Library
    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
-   connections alive at the same time (there's a default amount of 5 but that
+   connections alive at the same time.
-   can be changed with the CURLOPT_MAXCONNECTS option).
 
    This function cleans up all resources that are associated with a single
    connection.
 
- Curl_perform() is the function that does the main "connect - do - transfer -
- done" loop. It loops if there's a Location: to follow.
-
- When completed, the curl_easy_cleanup() should be called to free up used
- resources. It runs Curl_disconnect() on all open connections.
-
- A quick roundup on internal function sequences (many of these call
- protocol-specific function-pointers):
-
-  Curl_connect - connects to a remote site and does initial connect fluff
-   This also checks for an existing connection to the requested site and uses
-   that one if it is possible.
-
-   Curl_do - starts a transfer
-    Curl_handler::do_it() - transfers data
-   Curl_done - ends a transfer
-
-  Curl_disconnect - disconnects from a remote site. This is called when the
-   disconnect is really requested, which doesn't necessarily have to be
-   exactly after curl_done in case we want to keep the connection open for
-   a while.
 
  HTTP(S)
 
@@ -316,48 +296,38 @@ Persistent Connections
    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
-   pointers to 'connectdata' structs). There's one connectdata struct
+   pointers to 'connectdata' structs).
-   allocated for each connection that libcurl knows about. Note that when you
-   use the multi interface, the multi handle will hold the connection cache
-   and not the particular easy handle. This of course to allow all easy handles
-   in a multi stack to be able to share and re-use connections.
  o This enables the 'curl handle' to be reused on subsequent transfers.
- o When we are about to perform a transfer with curl_easy_perform(), we first
+ o When libcurl is told to perform a transfer, it first checks for an already
-   check for an already existing connection in the cache that we can use,
+   existing connection in the cache that we can use. Otherwise it creates a
-   otherwise we create a new one and add to the cache. If the cache is full
+   new one and adds that the cache. If the cache is full already when a new
-   already when we add a new connection, we close one of the present ones. We
+   connection is added added, it will first close the oldest unused one.
-   select which one to close dependent on the close policy that may have been
+ o When the transfer operation is complete, the connection is left
-   previously set.
+   open. Particular options may tell libcurl not to, and protocols may signal
- o When the transfer operation is complete, we try to leave the connection
+   closure on connections and then they won't be kept open of course.
-   open. Particular options may tell us not to, and protocols may signal
-   closure on connections and then we don't keep it open of course.
  o When curl_easy_cleanup() is called, we close all still opened connections,
    unless of course the multi interface "owns" the connections.
 
- You do realize that the curl handle must be re-used in order for the
+ The curl handle must be re-used in order for the persistent connections to
- persistent connections to work.
+ work.
 
 multi interface/non-blocking
 ============================
 
- We make an effort to provide a non-blocking interface to the library, the
+ The multi interface is a non-blocking interface to the library. To make that
- multi interface. To make that interface work as good as possible, no
+ interface work as good as possible, no low-level functions within libcurl
- low-level functions within libcurl must be written to work in a blocking
+ must be written to work in a blocking manner. (There are still a few spots
- manner.
+ violating this rule.)
 
  One of the primary reasons we introduced c-ares support was to allow the name
  resolve phase to be perfectly non-blocking as well.
 
- The ultimate goal is to provide the easy interface simply by wrapping the
+ The FTP and the SFTP/SCP protocols are examples of how we adapt and adjust
- multi interface functions and thus treat everything internally as the multi
+ the code to allow non-blocking operations even on multi-stage command-
- interface is the single interface we have.
+ response protocols. They are built around state machines that return when
-
+ they would otherwise block waiting for data.  The DICT, LDAP and TELNET
- The FTP and the SFTP/SCP protocols are thus perfect examples of how we adapt
+ protocols are crappy examples and they are subject for rewrite in the future
- and adjust the code to allow non-blocking operations even on multi-stage
+ to better fit the libcurl protocol family.
- protocols. They are built around state machines that return when they could
- block waiting for data.  The DICT, LDAP and TELNET protocols are crappy
- examples and they are subject for rewrite in the future to better fit the
- libcurl protocol family.
 
 SSL libraries
 =============
@@ -368,10 +338,10 @@ 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 sslgen.[ch] system, and they are the only SSL
+ function API as provided by the vtls.[ch] system, and they are the only SSL
- functions we must use from within libcurl. sslgen is then crafted to use the
+ 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.
+ use. For example vtls/openssl.[ch] for the OpenSSL library.
 
 Library Symbols
 ===============
@@ -408,12 +378,12 @@ API/ABI
 Client
 ======
 
- main() resides in src/main.c together with most of the client code.
+ main() resides in src/tool_main.c.
 
  src/tool_hugehelp.c is automatically generated by the mkhelp.pl perl script
- to display the complete "manual" and the src/urlglob.c file holds the
+ 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
+ functions used for the URL-"globbing" support. Globbing in the sense that the
- the {} and [] expansion stuff is there.
+ {} 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
@@ -425,8 +395,8 @@ Client
  curl_easy_getinfo() function to extract useful information from the curl
  session.
 
- Recent versions may loop and do all this several times if many URLs were
+ It may loop and do all this several times if many URLs were specified on the
- specified on the command line or config file.
+ command line or config file.
 
 Memory Debugging
 ================

docs/KNOWN_BUGS

@@ -3,20 +3,61 @@ join in and help us correct one or more of these! Also be sure to check the
 changelog of the current development status, as one or more of these problems
 may have been fixed since this was written!
 
+87. -J/--remote-header-name doesn't decode %-encoded file names. RFC6266
+  details how it should be done. The can of worm is basically that we have no
+  charset handling in curl and ascii >=128 is a challenge for us. Not to
+  mention that decoding also means that we need to check for nastiness that is
+  attempted, like "../" sequences and the like. Probably everything to the left
+  of any embedded slashes should be cut off.
+  http://curl.haxx.se/bug/view.cgi?id=1294
+
+86. The disconnect commands (LOGOUT and QUIT) may not be sent by IMAP, POP3
+  and SMTP if a failure occurs during the authentication phase of a
+  connection.
+
+85. Wrong STARTTRANSFER timer accounting for POST requests
+  Timer works fine with GET requests, but while using POST the time for
+  CURLINFO_STARTTRANSFER_TIME is wrong. While using POST
+  CURLINFO_STARTTRANSFER_TIME minus CURLINFO_PRETRANSFER_TIME is near to zero
+  every time.
+  http://curl.haxx.se/bug/view.cgi?id=1213
+
+84. CURLINFO_SSL_VERIFYRESULT is only implemented for the OpenSSL and NSS
+  backends, so relying on this information in a generic app is flaky.
+
+83. curl is unable to load non-default openssl engines, because openssl isn't
+  initialized properly. This seems to require OpenSSL_config() or
+  CONF_modules_load_file() to be used by libcurl but the first seems to not
+  work and we've gotten not reports from tests with the latter. Possibly we
+  need to discuss with OpenSSL developers how this is supposed to be done. We
+  need users with actual external openssl engines for testing to work on this.
+  http://curl.haxx.se/bug/view.cgi?id=1208
+
+82. When building with the Windows Borland compiler, it fails because the
+  "tlib" tool doesn't support hyphens (minus signs) in file names and we have
+  such in the build.
+  http://curl.haxx.se/bug/view.cgi?id=1222
+
+81. When using -J (with -O), automatically resumed downloading together with
+  "-C -" fails. Without -J the same command line works! This happens because
+  the resume logic is worked out before the target file name (and thus its
+  pre-transfer size) has been figured out!
+  http://curl.haxx.se/bug/view.cgi?id=1169
+
 80. Curl doesn't recognize certificates in DER format in keychain, but it
   works with PEM.
-  http://curl.haxx.se/bug/view.cgi?id=3439999
+  http://curl.haxx.se/bug/view.cgi?id=1065
 
 79. SMTP. When sending data to multiple recipients, curl will abort and return
   failure if one of the recipients indicate failure (on the "RCPT TO"
   command). Ordinary mail programs would proceed and still send to the ones
   that can receive data. This is subject for change in the future.
-  http://curl.haxx.se/bug/view.cgi?id=3438362
+  http://curl.haxx.se/bug/view.cgi?id=1116
 
 78. curl and libcurl don't always signal the client properly when "sending"
   zero bytes files - it makes for example the command line client not creating
   any file at all. Like when using FTP.
-  http://curl.haxx.se/bug/view.cgi?id=3438362
+  http://curl.haxx.se/bug/view.cgi?id=1063
 
 77. CURLOPT_FORBID_REUSE on a handle prevents NTLM from working since it
   "abuses" the underlying connection re-use system and if connections are
@@ -28,12 +69,12 @@ may have been fixed since this was written!
   option as for all other operating systems.
 
 75. NTLM authentication involving unicode user name or password only works
-  properly if built with UNICODE defined together with the schannel/winssl
+  properly if built with UNICODE defined together with the WinSSL/schannel
   backend. The original problem was mentioned in:
   http://curl.haxx.se/mail/lib-2009-10/0024.html
-  http://curl.haxx.se/bug/view.cgi?id=2944325
+  http://curl.haxx.se/bug/view.cgi?id=896
 
-  The schannel version verified to work as mentioned in
+  The WinSSL/schannel version verified to work as mentioned in
   http://curl.haxx.se/mail/lib-2012-07/0073.html
 
 73. if a connection is made to a FTP server but the server then just never
@@ -41,7 +82,7 @@ may have been fixed since this was written!
   acknowledge the connection timeout during that phase but only the "real"
   timeout - which may surprise users as it is probably considered to be the
   connect phase to most people. Brought up (and is being misunderstood) in:
-  http://curl.haxx.se/bug/view.cgi?id=2844077
+  http://curl.haxx.se/bug/view.cgi?id=856
 
 72. "Pausing pipeline problems."
   http://curl.haxx.se/mail/lib-2009-07/0214.html
@@ -59,7 +100,7 @@ may have been fixed since this was written!
   http://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=2818950
+  http://curl.haxx.se/bug/view.cgi?id=846
 
 65. When doing FTP over a socks proxy or CONNECT through HTTP proxy and the
   multi interface is used, libcurl will fail if the (passive) TCP connection
@@ -85,19 +126,12 @@ may have been fixed since this was written!
   CURLOPT_FAILONERROR with FTP to detect if a file exists or not, but it is
   not working: http://curl.haxx.se/mail/lib-2008-07/0295.html
 
-57. On VMS-Alpha: When using an http-file-upload the file is not sent to the
-  Server with the correct content-length.  Sending a file with 511 or less
-  bytes, content-length 512 is used.  Sending a file with 513 - 1023 bytes,
-  content-length 1024 is used.  Files with a length of a multiple of 512 Bytes
-  show the correct content-length. Only these files work for upload.
-  http://curl.haxx.se/bug/view.cgi?id=2057858
-
 56. When libcurl sends CURLOPT_POSTQUOTE commands when connected to a SFTP
   server using the multi interface, the commands are not being sent correctly
   and instead the connection is "cancelled" (the operation is considered done)
   prematurely. There is a half-baked (busy-looping) patch provided in the bug
   report but it cannot be accepted as-is. See
-  http://curl.haxx.se/bug/view.cgi?id=2006544
+  http://curl.haxx.se/bug/view.cgi?id=748
 
 55. libcurl fails to build with MIT Kerberos for Windows (KfW) due to KfW's
   library header files exporting symbols/macros that should be kept private
@@ -121,12 +155,12 @@ may have been fixed since this was written!
   protocol code. This should be very rare.
 
 43. There seems to be a problem when connecting to the Microsoft telnet server.
-  http://curl.haxx.se/bug/view.cgi?id=1720605
+  http://curl.haxx.se/bug/view.cgi?id=649
 
 41. When doing an operation over FTP that requires the ACCT command (but not
   when logging in), the operation will fail since libcurl doesn't detect this
   and thus fails to issue the correct command:
-  http://curl.haxx.se/bug/view.cgi?id=1693337
+  http://curl.haxx.se/bug/view.cgi?id=635
 
 39. Steffen Rumler's Race Condition in Curl_proxyCONNECT:
   http://curl.haxx.se/mail/lib-2007-01/0045.html
@@ -139,28 +173,18 @@ may have been fixed since this was written!
 
 34. The SOCKS4 connection codes don't properly acknowledge (connect) timeouts.
   Also see #12. According to bug #1556528, even the SOCKS5 connect code does
-  not do it right: http://curl.haxx.se/bug/view.cgi?id=1556528,
+  not do it right: http://curl.haxx.se/bug/view.cgi?id=604
 
 31. "curl-config --libs" will include details set in LDFLAGS when configure is
   run that might be needed only for building libcurl. Further, curl-config
   --cflags suffers from the same effects with CFLAGS/CPPFLAGS.
 
 30. You need to use -g to the command line tool in order to use RFC2732-style
-  IPv6 numerical addresses in URLs.
+  or RFC6874-style IPv6 numerical addresses in URLs.
-
-29. IPv6 URLs with zone ID is not nicely supported.
-  http://www.ietf.org/internet-drafts/draft-fenner-literal-zone-02.txt (expired)
-  specifies the use of a plus sign instead of a percent when specifying zone
-  IDs in URLs to get around the problem of percent signs being
-  special. According to the reporter, Firefox deals with the URL _with_ a
-  percent letter (which seems like a blatant URL spec violation).
-  libcurl supports zone IDs where the percent sign is URL-escaped (i.e. %25).
-
-   See http://curl.haxx.se/bug/view.cgi?id=1371118
 
 26. NTLM authentication using SSPI (on Windows) when (lib)curl is running in
   "system context" will make it use wrong(?) user name - at least when compared
-  to what winhttp does. See http://curl.haxx.se/bug/view.cgi?id=1281867
+  to what winhttp does. See http://curl.haxx.se/bug/view.cgi?id=535
 
 23. SOCKS-related problems:
   B) libcurl doesn't support FTPS over a SOCKS proxy.
@@ -169,12 +193,6 @@ may have been fixed since this was written!
   We probably have even more bugs and lack of features when a SOCKS proxy is
   used.
 
-22. Sending files to a FTP server using curl on VMS, might lead to curl
-  complaining on "unaligned file size" on completion. The problem is related
-  to VMS file structures and the perceived file sizes stat() returns. A
-  possible fix would involve sending a "STRU VMS" command.
-  http://curl.haxx.se/bug/view.cgi?id=1156287
-
 21. FTP ASCII transfers do not follow RFC959. They don't convert the data
    accordingly (not for sending nor for receiving). RFC 959 section 3.1.1.1
    clearly describes how this should be done:
@@ -212,7 +230,7 @@ may have been fixed since this was written!
 10. To get HTTP Negotiate authentication to work fine, you need to provide a
   (fake) user name (this concerns both curl and the lib) because the code
   wrongly only considers authentication if there's a user name provided.
-  http://curl.haxx.se/bug/view.cgi?id=1004841. How?
+  http://curl.haxx.se/bug/view.cgi?id=440 How?
   http://curl.haxx.se/mail/lib-2004-08/0182.html
 
 8. Doing resumed upload over HTTP does not work with '-C -', because curl

docs/LIBCURL-STRUCTS

@@ -0,0 +1,245 @@
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
+
+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.
+
+
+  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.
+
+  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.

docs/MAIL-ETIQUETTE

@@ -105,7 +105,7 @@ MAIL ETIQUETTE
   No matter what, we NEVER EVER respond to trolls or spammers on the list. If
   you believe the list admin should do something particular, contact him/her
   off-list. The subject will be taken care of as good as possible to prevent
-  repeated offences, but responding on the list to such messages never lead to
+  repeated offenses, but responding on the list to such messages never lead to
   anything good and only puts the light even more on the offender: which was
   the entire purpose of it getting to the list in the first place.
 

docs/MANUAL

@@ -50,7 +50,7 @@ SIMPLE USAGE
 
   Get the main page from an IPv6 web server:
 
-        curl -g "http://[2001:1890:1112:1::20]/"
+        curl "http://[2001:1890:1112:1::20]/"
 
 DOWNLOAD TO A FILE
 
@@ -956,9 +956,9 @@ IPv6
   When this style is used, the -g option must be given to stop curl from
   interpreting the square brackets as special globbing characters.  Link local
   and site local addresses including a scope identifier, such as fe80::1234%1,
-  may also be used, but the scope portion must be numeric and the percent
+  may also be used, but the scope portion must be numeric or match an existing
-  character must be URL escaped. The previous example in an SFTP URL might
+  network interface on Linux and the percent character must be URL escaped. The
-  look like:
+  previous example in an SFTP URL might look like:
 
     sftp://[fe80::1234%251]/
 

docs/Makefile.am

@@ -5,7 +5,7 @@
 #                            | (__| |_| |  _ <| |___
 #                             \___|\___/|_| \_\_____|
 #
-# Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+# Copyright (C) 1998 - 2014, 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
@@ -22,7 +22,8 @@
 
 AUTOMAKE_OPTIONS = foreign no-dependencies
 
-man_MANS = curl.1 curl-config.1 mk-ca-bundle.1
+man_MANS = curl.1 curl-config.1
+noinst_man_MANS = mk-ca-bundle.1
 GENHTMLPAGES = curl.html curl-config.html mk-ca-bundle.html
 PDFPAGES = curl.pdf curl-config.pdf mk-ca-bundle.pdf
 
@@ -36,7 +37,8 @@ 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
+ MAIL-ETIQUETTE HTTP-COOKIES LIBCURL-STRUCTS SECURITY RELEASE-PROCEDURE  \
+ SSL-PROBLEMS
 
 MAN2HTML= roffit < $< >$@
 

docs/README.netware

@@ -10,7 +10,7 @@ README.netware
 
   Curl has been successfully compiled with gcc / nlmconv on different flavours
   of Linux as well as with the official Metrowerks CodeWarrior compiler.
-  While not being the main development target, a continously growing share of
+  While not being the main development target, a continuously growing share of
   curl users are NetWare-based, specially also consuming the lib from PHP.
 
   The unix-style man pages are tricky to read on windows, so therefore are all

docs/RELEASE-PROCEDURE

@@ -0,0 +1,53 @@
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
+
+curl release procedure - how to do a release
+============================================
+
+[in the source code repo]
+
+- edit RELEASE-NOTES to be accurate
+
+- update docs/THANKS
+
+- make sure all relevant changes are committed on the master branch
+
+- tag the git repo in this style: 'git tag -a curl-7_34_0'. -a annotates the
+  tag and we use underscores instead of dots in the version number. 
+   
+- run "./maketgz 7.34.0" to build the release tarballs. It is important that
+  you run this on a machine with the correct set of autotools etc installed
+  as this is what then will be shipped and used by most users on *nix like
+  systems.
+
+- push the git commits and the new tag
+
+- gpg sign the 4 tarballs as maketgz suggests
+
+- upload the 8 resulting files to the primary download directory
+
+[data in the curl-www repo]
+
+- edit Makefile (version number and date),
+  _newslog.html (announce the new release) and
+  _changes.html (insert changes+bugfixes from RELEASE-NOTES)
+
+- commit all local changes
+
+- tag the repo with the same tag as used for the source repo
+
+- make sure all relevant changes are committed and pushed on the master branch
+
+  (the web site then updates its contents automatically)
+
+[inform]
+
+- send an email to curl-users, curl-announce and curl-library. Insert the
+  RELEASE-NOTES into the mail.
+
+[celebrate]
+
+- suitable beverage intake is encouraged for the festivities

docs/SECURITY

@@ -0,0 +1,91 @@
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
+
+CURL SECURITY FOR DEVELOPERS
+
+This document is intended to provide guidance to curl developers on how
+security vulnerabilities should be handled.
+
+PUBLISHING INFORMATION
+
+All known and public curl or libcurl related vulnerabilities are listed at
+http://curl.haxx.se/docs/security.html
+
+Security vulnerabilities should not be entered in the project's public bug
+tracker unless the necessary configuration is in place to limit access to the
+issue to only the reporter and the project's security team.
+
+VULNERABILITY HANDLING
+
+The typical process for handling a new security vulnerability is as follows.
+
+No information should be made public about a vulnerability until it is
+formally announced at the end of this process. That means, for example that a
+bug tracker entry must NOT be created to track the issue since that will make
+the issue public and it should not be discussed on any of the project's public
+mailing lists. Also messages associated with any commits should not make
+any reference to the security nature of the commit if done prior to the public
+announcement.
+
+- The person discovering the issue, the reporter, reports the vulnerability
+  privately to curl-security@haxx.se. That's an email alias that reaches a
+  handful of selected and trusted people.
+
+- Messages that do not relate to the reporting or managing of an undisclosed
+  security vulnerability in curl or libcurl are ignored and no further action
+  is required.
+
+- A person in the security team sends an e-mail to the original reporter to
+  acknowledge the report.
+
+- The security team investigates the report and either rejects it or accepts
+  it.
+
+- If the report is rejected, the team writes to the reporter to explain why.
+
+- If the report is accepted, the team writes to the reporter to let him/her
+  know it is accepted and that they are working on a fix.
+
+- The security team discusses the problem, works out a fix, considers the
+  impact of the problem and suggests a release schedule. This discussion
+  should involve the reporter as much as possible.
+
+- The release of the information should be "as soon as possible" and is most
+  often synced with an upcoming release that contains the fix. If the
+  reporter, or anyone else, thinks the next planned release is too far away
+  then a separate earlier release for security reasons should be considered.
+
+- Write a security advisory draft about the problem that explains what the
+  problem is, its impact, which versions it affects, solutions or
+  workarounds, when the release is out and make sure to credit all
+  contributors properly.
+
+- Request a CVE number from distros@openwall.org[1] when also informing and
+  preparing them for the upcoming public security vulnerability announcement -
+  attach the advisory draft for information. Note that 'distros' won't accept
+  an embargo longer than 19 days.
+
+- Update the "security advisory" with the CVE number.
+
+- The security team commits the fix in a private branch. The commit message
+  should ideally contain the CVE number. This fix is usually also distributed
+  to the 'distros' mailing list to allow them to use the fix prior to the
+  public announcement.
+
+- At the day of the next release, the private branch is merged into the master
+  branch and pushed. Once pushed, the information is accessible to the public
+  and the actual release should follow suit immediately afterwards.
+
+- The project team creates a release that includes the fix.
+
+- The project team announces the release and the vulnerability to the world in
+  the same manner we always announce releases. It gets sent to the
+  curl-announce, curl-library and curl-users mailing lists.
+
+- The security web page on the web site should get the new vulnerability
+  mentioned.
+
+[1] = http://oss-security.openwall.org/wiki/mailing-lists/distros

docs/SSL-PROBLEMS

@@ -0,0 +1,67 @@
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
+
+SSL problems
+
+  First, let's establish that we often refer to TLS and SSL interchangeably as
+  SSL here. The current protocol is called TLS, it was called SSL a long time
+  ago.
+
+  There are several known reasons why a connection that involves SSL might
+  fail. This is a document that attempts to details the most common ones and
+  how to mitigate them.
+
+CA certs
+
+  CA certs are used to digitally verify the server's certificate. You need a
+  "ca bundle" for this. See lots of more details on this in the SSLCERTS
+  document.
+
+CA bundle missing intermediate certificates
+
+  When using said CA bundle to verify a server cert, you will experience
+  problems if your CA cert does not have the certificates for the
+  intermediates in the whole trust chain.
+
+SSL version
+
+  Some broken servers fail to support the protocol negotiation properly that
+  SSL servers are supposed to handle. This may cause the connection to fail
+  completely. Sometimes you may need to explicitly select a SSL version to use
+  when connecting to make the connection succeed.
+
+  An additional complication can be that modern SSL libraries sometimes are
+  built with support for older SSL and TLS versions disabled!
+
+SSL ciphers
+
+  Clients give servers a list of ciphers to select from. If the list doesn't
+  include any ciphers the server wants/can use, the connection handshake
+  fails.
+
+  curl has recently disabled the user of a whole bunch of seriously insecure
+  ciphers from its default set (slightly depending on SSL backend in use).
+
+  You may have to explicitly provide an alternative list of ciphers for curl
+  to use to allow the server to use a WEAK cipher for you.
+
+  Note that these weak ciphers are identified as flawed. For example, this
+  includes symmetric ciphers with less than 128 bit keys and RC4.
+
+  References:
+
+  http://tools.ietf.org/html/draft-popov-tls-prohibiting-rc4-01
+  
+Allow BEAST
+
+  BEAST is the name of a TLS 1.0 attack that surfaced 2011. When adding means
+  to mitigate this attack, it turned out that some broken servers out there in
+  the wild didn't work properly with the BEAST mitigation in place.
+
+  To make such broken servers work, the --ssl-allow-beast option was
+  introduced. Exactly as it sounds, it re-introduces the BEAST vulnerability
+  but on the other hand it allows curl to connect to that kind of strange
+  servers.

docs/SSLCERTS

@@ -1,6 +1,12 @@
                       Peer SSL Certificate Verification
                       =================================
 
+(NOTE: If libcurl was built with Schannel or Secure Transport support, then
+this does not apply to you. Scroll down for details on how the OS-native
+engines handle SSL certificates. If you're not sure, then run "curl -V" and
+read the results. If the version string says "WinSSL" in it, then it was built
+with Schannel support.)
+
 libcurl performs peer SSL certificate verification by default.  This is done
 by using CA cert bundle that the SSL library can use to make sure the peer's
 server certificate is valid.
@@ -93,24 +99,40 @@ server.
                       Peer SSL Certificate Verification with NSS
                       ==========================================
 
-If libcurl is build with NSS support then depending on the OS distribution it
+If libcurl was built with NSS support, then depending on the OS distribution,
-is probably required to take some additional steps to use the system-wide CA
+it is probably required to take some additional steps to use the system-wide CA
-cert db. RedHat ships with an additional module libnsspem.so which enables NSS
+cert db. RedHat ships with an additional module, libnsspem.so, which enables
-to read the OpenSSL PEM CA bundle. With OpenSuSE this lib is missing, and NSS
+NSS to read the OpenSSL PEM CA bundle. This library is missing in OpenSuSE, and
-can only work with its own internal formats. Also NSS got a new database
+without it, NSS can only work with its own internal formats. NSS also has a new
-format:
+database format: https://wiki.mozilla.org/NSS_Shared_DB
-https://wiki.mozilla.org/NSS_Shared_DB
+
-Starting with version 7.19.7 libcurl will check for the NSS version it runs,
+Starting with version 7.19.7, libcurl will check for the NSS version it runs,
-and add automatically the 'sql:' prefix to the certdb directory (either the
+and automatically add the 'sql:' prefix to the certdb directory (either the
 hardcoded default /etc/pki/nssdb or the directory configured with SSL_DIR
-environment variable) if a version 3.12.0 or later is detected.
+environment variable) if version 3.12.0 or later is detected. To check which
-To check which certdb format your distribution provides examine the default
+certdb format your distribution provides, examine the default
-certdb location /etc/pki/nssdb; the new certdb format can be identified by
+certdb location: /etc/pki/nssdb; the new certdb format can be identified by
 the filenames cert9.db, key4.db, pkcs11.txt; filenames of older versions are
 cert8.db, key3.db, modsec.db.
-Usually these cert databases are empty; but NSS also has built-in CAs which are
+
-provided through a shared library libnssckbi.so; if you want to use these
+Usually these cert databases are empty, but NSS also has built-in CAs which are
-built-in CAs then create a symlink to libnssckbi.so in /etc/pki/nssdb:
+provided through a shared library, libnssckbi.so; if you want to use these
+built-in CAs, then create a symlink to libnssckbi.so in /etc/pki/nssdb:
 ln -s /usr/lib[64]/libnssckbi.so /etc/pki/nssdb/libnssckbi.so
 
+     Peer SSL Certificate Verification with Schannel and Secure Transport
+     ====================================================================
 
+If libcurl was built with Schannel (Microsoft's TLS/SSL engine) or Secure
+Transport (Apple's TLS/SSL engine) support, then libcurl will still perform
+peer certificate verification, but instead of using a CA cert bundle, it will
+use the certificates that are built into the OS. These are the same
+certificates that appear in the Internet Options control panel (under Windows)
+or Keychain Access application (under OS X). Any custom security rules for
+certificates will be honored.
+
+Schannel will run CRL checks on certificates unless peer verification is
+disabled. Secure Transport on iOS will run OCSP checks on certificates unless
+peer verification is disabled. Secure Transport on OS X will run either OCSP
+or CRL checks on certificates if those features are enabled, and this behavior
+can be adjusted in the preferences of Keychain Access.

docs/THANKS

@@ -4,33 +4,39 @@
 
  If you have contributed but are missing here, please let us know!
 
+Aaro Koskinen
 Aaron Oneal
 Aaron Orenstein
+Abram Pousada
 Adam D. Moss
 Adam Light
 Adam Piggott
+Adam Sampson
 Adam Tkac
 Adrian Schuur
 Adriano Meirelles
 Ajit Dhumale
+Aki Koskinen
 Akos Pasztory
 Alan Pinstein
-Albert Chin
 Albert Chin-A-Young
 Albert Choy
 Ale Vesely
 Alejandro Alvarez
 Aleksandar Milivojevic
+Aleksey Tulinov
 Alessandro Ghedini
 Alessandro Vesely
 Alex Bligh
 Alex Fishman
 Alex Gruz
+Alex McLellan
 Alex Neblett
 Alex Suykov
 Alex Vinnik
 Alex aka WindEagle
 Alexander Beedie
+Alexander Klauer
 Alexander Kourakos
 Alexander Krasnostavsky
 Alexander Lazic
@@ -46,11 +52,13 @@ Amol Pattekar
 Amr Shahin
 Anatoli Tubman
 Anders Gustafsson
+Anders Havn
 Andi Jahja
 Andre Guibert de Bruet
 Andreas Damm
 Andreas Faerber
 Andreas Farber
+Andreas Malzahn
 Andreas Ntaflos
 Andreas Olsson
 Andreas Rieke
@@ -58,15 +66,18 @@ Andreas Schuldei
 Andreas Wurf
 Andrei Benea
 Andrei Cipu
+Andrej E Baranov
 Andres Garcia
 Andrew Benham
 Andrew Biggs
 Andrew Bushnell
 Andrew Francis
 Andrew Fuller
+Andrew Kurushin
 Andrew Moise
 Andrew Wansink
 Andrew de los Reyes
+Andrii Moiseiev
 Andrés García
 Andy Cedilnik
 Andy Serpa
@@ -85,11 +96,14 @@ Arnaud Compan
 Arnaud Ebalard
 Arthur Murray
 Arve Knudsen
+Arvid Norberg
 Ates Goral
 Augustus Saunders
 Avery Fay
 Axel Tillequin
+Balaji Parasuram
 Balint Szilakszi
+Barry Abrahamson
 Bart Whiteley
 Bas Mevissen
 Ben Darnell
@@ -100,23 +114,29 @@ Ben Van Hof
 Ben Winslow
 Benbuck Nason
 Benjamin Gerard
+Benjamin Gilbert
 Benjamin Johnson
+Benoit Sigoure
 Bernard Leak
 Bernhard Reutner-Fischer
 Bertrand Demiddelaer
+Bill Doyle
 Bill Egert
 Bill Hoffman
+Bill Middlecamp
 Bjoern Sikora
 Bjorn Augustsson
 Bjorn Reese
 Björn Stenberg
 Blaise Potard
+Bob Relyea
 Bob Richmond
 Bob Schader
 Bogdan Nicula
 Brad Burdick
 Brad Hards
 Brad King
+Brad Spencer
 Bradford Bruce
 Brandon Wang
 Brendan Jurd
@@ -128,8 +148,10 @@ Brian R Duffy
 Brian Ulm
 Brock Noland
 Bruce Mitchener
+Bruno de Carvalho
 Bryan Henderson
 Bryan Kemp
+Byrial Jensen
 Cameron Kaiser
 Camille Moncelier
 Caolan McNamara
@@ -139,9 +161,11 @@ Cedric Deltheil
 Chad Monroe
 Chandrakant Bagul
 Charles Kerr
+Chen Prog
 Chih-Chung Chang
 Chris "Bob Bob"
 Chris Combes
+Chris Conlon
 Chris Conroy
 Chris Deidun
 Chris Flerackers
@@ -150,13 +174,13 @@ Chris Maltby
 Chris Mumford
 Chris Smowton
 Christian Grothoff
-Christian Hagele
 Christian Hägele
 Christian Krause
 Christian Kurz
 Christian Robottom Reis
 Christian Schmitz
 Christian Vogt
+Christian Weisgerber
 Christophe Demory
 Christophe Legry
 Christopher Conroy
@@ -166,8 +190,11 @@ Christopher Stone
 Ciprian Badescu
 Claes Jakobsson
 Clarence Gardner
+Clemens Gruber
 Clifford Wolf
 Cody Jones
+Cody Mack
+Colby Ranger
 Colin Hogben
 Colin Watson
 Colm Buckley
@@ -177,12 +204,14 @@ Craig A West
 Craig Davison
 Craig Markwardt
 Cris Bailiff
-Cristian Rodriguez
 Cristian Rodríguez
 Curt Bogmine
 Cyrill Osterwalder
+Cédric Deltheil
+D. Flinkmann
 Dag Ekengren
 Dagobert Michelsen
+Damian Dixon
 Damien Adant
 Dan Becker
 Dan C
@@ -208,6 +237,7 @@ Dave Halbakken
 Dave Hamilton
 Dave May
 Dave Reisner
+Dave Thompson
 Dave Vasilevsky
 David Bau
 David Binderman
@@ -227,16 +257,23 @@ David McCreedy
 David Odin
 David Phillips
 David Rosenstrauch
+David Ryskalczyk
 David Shaw
+David Strauss
 David Tarendash
 David Thiel
+David Walser
+David Woodhouse
 David Wright
 David Yan
 Dengminwen
+Derek Higgins
 Detlef Schmier
 Didier Brisebourg
 Diego Casorran
+Dilyan Palauzov
 Dima Barsky
+Dima Tisnek
 Dimitre Dimitrov
 Dimitris Sarris
 Dinar
@@ -260,6 +297,7 @@ Douglas R. Horner
 Douglas Steinwand
 Dov Murik
 Duane Cathey
+Duncan
 Duncan Mac-Vicar Prett
 Dustin Boswell
 Dylan Ellicott
@@ -268,10 +306,13 @@ Early Ehlinger
 Ebenezer Ikonne
 Edin Kadribasic
 Eduard Bloch
+Edward Rudd
 Edward Sheldrake
 Eelco Dolstra
 Eetu Ojanen
+Eldar Zaitov
 Ellis Pritchard
+Elmira A Semenova
 Emanuele Bovisio
 Emil Romanus
 Emiliano Ida
@@ -281,27 +322,34 @@ Eric Cooper
 Eric Hu
 Eric Landes
 Eric Lavigne
+Eric Lubin
 Eric Melville
 Eric Mertens
 Eric Rautman
+Eric S. Raymond
 Eric Thelin
 Eric Vergnaud
 Eric Wong
 Eric Young
 Erick Nuwendam
+Erik Johansson
 Erwan Legrand
 Erwin Authried
 Eugene Kotlyarov
 Evan Jordan
+Evgeny Turnaev
 Eygene Ryabinkin
+Fabian Frank
 Fabian Hiernaux
 Fabian Keil
 Fabrizio Ammollo
 Fedor Karpelevitch
+Felix Yan
 Felix von Leitner
 Feng Tu
 Florian Schoppmann
 Forrest Cahoon
+Francois Charlier
 Frank Hempel
 Frank Keeney
 Frank McGeough
@@ -313,6 +361,7 @@ Fred Machado
 Fred New
 Fred Noz
 Frederic Lepied
+Fredrik Thulin
 Gabriel Kuri
 Gabriel Sjoberg
 Garrett Holmstrom
@@ -321,11 +370,14 @@ Gautam Kachroo
 Gautam Mani
 Gavrie Philipson
 Gaz Iqbal
+Gaël Portay
+Geoff Beier
 Georg Horn
 Georg Huettenegger
 Georg Lippitsch
 Georg Wicherski
 Gerd v. Egidy
+Gergely Nagy
 Gerhard Herre
 Gerrit Bruchhäuser
 Ghennadi Procopciuc
@@ -340,7 +392,10 @@ Giuseppe Attardi
 Giuseppe D'Ambrosio
 Glen Nakamura
 Glen Scott
+Glenn Sheridan
 Gokhan Sengun
+Gordon Marler
+Gorilla Maguila
 Grant Erickson
 Greg Hewgill
 Greg Morse
@@ -356,14 +411,17 @@ Gwenole Beauchesne
 Götz Babin-Ebell
 Hamish Mackenzie
 Hang Kin Lau
+Hang Su
 Hanno Kranzhoff
 Hans Steegers
 Hans-Jurgen May
 Hardeep Singh
 Harshal Pradhan
 Hauke Duden
+He Qin
 Heikki Korpela
 Heinrich Ko
+Heinrich Schaefer
 Hendrik Visage
 Henrik Storner
 Henry Ludemann
@@ -373,6 +431,7 @@ Ho-chi Chen
 Hoi-Ho Chan
 Hongli Lai
 Howard Chu
+Hubert Kario
 Hzhijun
 Ian D Allen
 Ian Ford
@@ -384,12 +443,15 @@ Ignacio Vazquez-Abrams
 Igor Franchuk
 Igor Novoseltsev
 Igor Polyakov
+Iida Yosiaki
 Ilguiz Latypov
 Ilja van Sprundel
 Immanuel Gregoire
 Ingmar Runge
 Ingo Ralf Blum
 Ingo Wilken
+Ishan SinghLevett
+Ivo Bellin Salarin
 Jack Zhang
 Jacky Lam
 Jacob Meuser
@@ -399,6 +461,7 @@ James Bursa
 James Cheng
 James Clancy
 James Cone
+James Dury
 James Gallagher
 James Griffiths
 James Housley
@@ -411,12 +474,14 @@ Jan Koen Annot
 Jan Kunder
 Jan Schaumann
 Jan Van Boghout
+Jared Jennings
 Jared Lundell
 Jari Sundell
 Jason Glasgow
 Jason Liu
 Jason McDonald
 Jason S. Priebe
+Javier Barroso
 Jay Austin
 Jayesh A Shah
 Jaz Fresh
@@ -425,17 +490,23 @@ Jean-Claude Chauve
 Jean-Francois Bertrand
 Jean-Louis Lemaire
 Jean-Marc Ranger
+Jean-Noel Rouvignac
 Jean-Philippe Barrette-LaPierre
 Jeff Connelly
+Jeff Hodges
 Jeff Johnson
+Jeff King
 Jeff Lawson
 Jeff Phillips
 Jeff Pohlmeyer
 Jeff Weber
 Jeffrey Pohlmeyer
 Jeremy Friesner
+Jeremy Huddleston
+Jeroen Koekkoek
 Jerome Muffat-Meridol
 Jerome Vouillon
+Jerry Krinock
 Jerry Wu
 Jes Badwal
 Jesper Jensen
@@ -445,6 +516,9 @@ Jim Drash
 Jim Freeman
 Jim Hollinger
 Jim Meyering
+Jiri Hruska
+Jiri Jaburek
+Jiri Malak
 Jocelyn Jaubert
 Joe Halpin
 Joe Malicki
@@ -458,7 +532,9 @@ Johannes Bauer
 John Bradshaw
 John Crow
 John Dennis
+John Dunn
 John E. Malmberg
+John Gardiner Myers
 John Janssen
 John Joseph Bachir
 John Kelly
@@ -474,6 +550,7 @@ Johnny Luong
 Jon Grubbs
 Jon Nelson
 Jon Sargeant
+Jon Torrey
 Jon Travis
 Jon Turner
 Jonas Forsman
@@ -500,8 +577,11 @@ Julien Royer
 Jun-ichiro itojun Hagino
 Jurij Smakov
 Justin Fletcher
+Justin Karneges
+Justin Maggard
 Jörg Mueller-Tolk
 Jörn Hartroth
+Kai Engert
 Kai Sommerfeld
 Kai-Uwe Rommel
 Kalle Vahlman
@@ -527,31 +607,38 @@ Kevin Lussier
 Kevin Reed
 Kevin Roth
 Kim Rinnewitz
+Kim Vandry
 Kimmo Kinnunen
 Kjell Ericson
 Kjetil Jacobsen
 Klevtsov Vadim
+Konstantin Isakov
 Kris Kennaway
 Krishnendu Majumdar
 Krister Johansen
 Kristian Gunstone
 Kristian Köhntopp
+Kyle L. Huff
 Kyle Sallee
 Lachlan O'Dea
 Larry Campbell
 Larry Fahnoe
+Larry Lin
 Lars Buitinck
 Lars Gustafsson
 Lars J. Aas
+Lars Johannesen
 Lars Nilsson
 Lars Torben Wilson
 Lau Hang Kin
 Laurent Rabret
 Legoff Vincent
 Lehel Bernadt
+Leif W
 Len Krause
 Lenaic Lefever
 Lenny Rachitsky
+Leon Winter
 Liam Healy
 Lijo Antony
 Linas Vepstas
@@ -559,28 +646,36 @@ Ling Thio
 Linus Nielsen Feltzing
 Lisa Xu
 Liza Alenchery
+Lluís Batlle i Rossell
 Loic Dachary
 Loren Kirkby
 Luca Altea
 Luca Alteas
 Lucas Adamski
+Ludovico Cavedon
 Lukasz Czekierda
 Luke Amery
 Luke Call
+Luke Dashjr
 Luong Dinh Dung
 Maciej Karpiuk
+Maciej Puzio
 Maciej W. Rozycki
+Maks Naumov
 Mamoru Tasaka
 Mandy Wu
 Manfred Schwarb
 Manuel Massing
 Marc Boucher
+Marc Deslauriers
+Marc Doughty
 Marc Hoersken
 Marc Kleine-Budde
 Marcel Raad
 Marcel Roelofs
 Marcelo Juchem
 Marcin Adamski
+Marcin Gryszkalis
 Marcin Konicki
 Marco G. Salvagno
 Marco Maggi
@@ -606,6 +701,7 @@ Martin C. Martin
 Martin Drasar
 Martin Hager
 Martin Hedenfalk
+Martin Jansen
 Martin Lemke
 Martin Skinner
 Martin Storsjo
@@ -616,6 +712,7 @@ Massimo Callegari
 Mateusz Loskot
 Mathias Axelsson
 Mats Lidell
+Matt Arsenault
 Matt Kraai
 Matt Veenstra
 Matt Witherspoon
@@ -633,6 +730,7 @@ Maxim Prohorov
 Maxime Larocque
 Mehmet Bozkurt
 Mekonikum
+Melissa Mears
 Mettgut Jamalla
 Michael Benedict
 Michael Calmer
@@ -644,6 +742,7 @@ Michael Jahn
 Michael Jerris
 Michael Mealling
 Michael Mueller
+Michael Osipov
 Michael Smith
 Michael Stillwell
 Michael Wallner
@@ -652,21 +751,28 @@ Michal Gorny
 Michal Kowalczyk
 Michal Marek
 Michele Bini
+Miguel Angel
 Mihai Ionescu
 Mikael Johansson
 Mikael Sennerholm
 Mike Bytnar
 Mike Crowe
 Mike Dobbs
+Mike Giancola
+Mike Hasselberg
 Mike Hommey
+Mike Mio
 Mike Power
 Mike Protts
 Mike Revi
 Miklos Nemeth
 Mitz Wark
 Mohamed Lrhazi
+Mohammad AlSaleh
 Mohun Biswas
 Moonesamy
+Myk Taylor
+Nach M. S.
 Nathan Coulter
 Nathan O'Sullivan
 Nathanael Nerode
@@ -700,6 +806,8 @@ Ofer
 Olaf Flebbe
 Olaf Stueben
 Olaf Stüben
+Oliver Gondža
+Oliver Kuckertz
 Olivier Berger
 Oren Tirosh
 Ori Avtalion
@@ -707,18 +815,23 @@ Oscar Koeroo
 Oscar Norlander
 P R Schaffner
 Paolo Piacentini
+Paras Sethia
 Pascal Terjan
 Pasha Kuznetsov
 Pat Ray
 Patrice Guerin
+Patricia Muscalu
 Patrick Bihan-Faou
 Patrick Monnerat
 Patrick Scott
 Patrick Smith
+Patrick Watson
 Patrik Thunstrom
 Pau Garcia i Quiles
+Paul Donohue
 Paul Harrington
 Paul Howarth
+Paul Marks
 Paul Marquis
 Paul Moore
 Paul Nolan
@@ -733,6 +846,7 @@ Pedro Neves
 Pete Su
 Peter Bray
 Peter Forret
+Peter Gal
 Peter Heuchert
 Peter Hjalmarsson
 Peter Korsgaard
@@ -746,6 +860,9 @@ Peter Todd
 Peter Verhas
 Peter Wullinger
 Peteris Krumins
+Petr Bahula
+Petr Novak
+Petr Pisar
 Phil Blundell
 Phil Karn
 Phil Lisiecki
@@ -763,13 +880,17 @@ Pierre Joye
 Pierre Ynard
 Pooyan McSporran
 Pramod Sharma
+Prash Dush
+Priyanka Shah
 Puneet Pawaia
 Quagmire
 Quanah Gibson-Mount
 Quinn Slack
+Radu Simionescu
 Rafa Muyo
 Rafael Sagula
 Rainer Canavan
+Rainer Jung
 Rainer Koenig
 Rajesh Naganathan
 Ralf S. Engelschall
@@ -781,9 +902,11 @@ Ravi Pratap
 Ray Dassen
 Ray Pekowski
 Reinout van Schouwen
+Remi Gacogne
 Renato Botelho
 Renaud Chaillat
 Renaud Duhaut
+Renaud Guillard
 Rene Bernhardt
 Rene Rebe
 Reuven Wachtfogel
@@ -797,11 +920,13 @@ Richard Bramante
 Richard Clayton
 Richard Cooper
 Richard Gorton
+Richard Michael
 Richard Prescott
 Richard Silverman
 Rick Jones
 Rick Richardson
 Rob Crittenden
+Rob Davies
 Rob Jones
 Rob Stanzel
 Rob Ward
@@ -813,6 +938,7 @@ Robert Iakobashvili
 Robert Olson
 Robert Schumann
 Robert Weaver
+Robert Wruck
 Robin Cornelius
 Robin Johnson
 Robin Kay
@@ -825,18 +951,22 @@ Roland Zimmermann
 Rolland Dudemaine
 Roman Koifman
 Roman Mamedov
+Romulo A. Ceccon
 Ron Zapp
 Rosimildo da Silva
 Roy Shan
 Rune Kleveland
 Ruslan Gazizov
 Rutger Hofman
+Ryan Braud
 Ryan Chan
 Ryan Nelson
 Ryan Schmidt
+Rémy Léone
 S. Moonesamy
 Salvador Dávila
 Salvatore Sorrentino
+Sam Deane
 Sam Listopad
 Sampo Kellomaki
 Samuel Díaz García
@@ -847,6 +977,7 @@ Sandor Feldi
 Santhana Todatry
 Saqib Ali
 Sara Golemon
+Saran Neti
 Saul good
 Scott Bailey
 Scott Barrett
@@ -857,11 +988,14 @@ Sebastian Rasmussen
 Sebastien Willemijns
 Senthil Raja Velu
 Sergei Nikulov
+Sergey Tatarincev
 Sergio Ballestrero
 Seshubabu Pasam
 Sh Diao
+Shao Shuchao
 Sharad Gupta
 Shard
+Shawn Landden
 Shawn Poulson
 Shmulik Regev
 Siddhartha Prakash Jain
@@ -876,8 +1010,10 @@ Spacen Jasset
 Spiridonoff A.V
 Stadler Stephan
 Stan van de Burgt
+Stanislav Ivochkin
 Stefan Esser
 Stefan Krause
+Stefan Neis
 Stefan Teleman
 Stefan Tomanek
 Stefan Ulrich
@@ -896,6 +1032,7 @@ Steve Oliphant
 Steve Roskowski
 Steven Bazyl
 Steven G. Johnson
+Steven Gu
 Steven M. Schweda
 Steven Parkes
 Stoned Elipot
@@ -909,12 +1046,15 @@ Taneli Vahakangas
 Tanguy Fautre
 Tatsuhiro Tsujikawa
 Temprimus
+Thomas Braun
 Thomas J. Moore
 Thomas Klausner
 Thomas L. Shinnick
 Thomas Lopatic
 Thomas Schwinge
 Thomas Tonino
+Tiit Pikma
+Till Maas
 Tim Ansell
 Tim Baker
 Tim Bartley
@@ -924,7 +1064,9 @@ Tim Harder
 Tim Heckman
 Tim Newsome
 Tim Sneddon
+Timo Sirainen
 Tinus van den Berg
+Tobias Markus
 Tobias Rundström
 Toby Peterson
 Todd A Ouska
@@ -933,13 +1075,16 @@ Todd Ouska
 Todd Vierling
 Tom Benoist
 Tom Donovan
+Tom Grace
 Tom Lee
 Tom Mattison
 Tom Moers
 Tom Mueller
 Tom Regner
+Tom Sparrow
 Tom Wright
 Tom Zerucha
+Tomas Hoger
 Tomas Mlcoch
 Tomas Pospisek
 Tomas Szepe
@@ -957,11 +1102,17 @@ Traian Nicolescu
 Troels Walsted Hansen
 Troy Engel
 Tupone Alfredo
+Tyler Hall
+Török Edwin
 Ulf Härnhammar
+Ulf Samuelsson
+Ulrich Doehner
 Ulrich Zadow
 Venkat Akella
 Victor Snezhko
+Vijay Panghal
 Vikram Saxena
+Viktor Szakáts
 Vilmos Nebehaj
 Vincent Bronner
 Vincent Le Normand
@@ -983,15 +1134,26 @@ Wesley Laxton
 Wesley Miaw
 Wez Furlong
 Wilfredo Sanchez
+Will Dietz
+Willem Sparreboom
 Wojciech Zwiefka
+Wouter Van Rooy
 Wu Yongzheng
 Xavier Bouchoux
+Yaakov Selkowitz
+Yamada Yasuharu
 Yang Tse
 Yarram Sunil
+Yehezkel Horowitz
 Yehoshua Hershberg
+Yi Huang
+Yingwei Liu
 Yukihiro Kawada
 Yuriy Sosov
+Yves Arrouye
 Yves Lejeune
+Zdenek Pavlas
+Zekun Ni
 Zmey Petroff
 Zvi Har'El
 nk

docs/TODO

@@ -16,28 +16,30 @@
  1.3 struct lifreq
  1.4 signal-based resolver timeouts
  1.5 get rid of PATH_MAX
- 1.6 progress callback without doubles
+ 1.6 Modified buffer size approach
- 1.7 Happy Eyeball dual stack connect
+ 1.7 Detect when called from within callbacks
+ 1.8 Allow SSL (HTTPS) to proxy
 
  2. libcurl - multi interface
  2.1 More non-blocking
  2.2 Fix HTTP Pipelining for PUT
 
  3. Documentation
- 3.1  More and better
+ 3.1 Update date and version in man pages
 
  4. FTP
  4.1 HOST
  4.2 Alter passive/active on failure and retry
  4.3 Earlier bad letter detection
  4.4 REST for large files
- 4.5 FTP proxy support
+ 4.5 ASCII support
- 4.6 ASCII support
 
  5. HTTP
  5.1 Better persistency for HTTP 1.0
  5.2 support FF3 sqlite cookie files
  5.3 Rearrange request header order
+ 5.4 SPDY
+ 5.5 auth= in URLs
 
  6. TELNET
  6.1 ditch stdin
@@ -45,36 +47,36 @@
  6.3 feature negotiation debug data
  6.4 send data in chunks
 
- 7. SSL
+ 7. SMTP
- 7.1 Disable specific versions
+ 7.1 Pipelining
- 7.2 Provide mutex locking API
+ 7.2 Enhanced capability support
- 7.3 Evaluate SSL patches
- 7.4 Cache OpenSSL contexts
- 7.5 Export session ids
- 7.6 Provide callback for cert verification
- 7.7 Support other SSL libraries
- 7.9 improve configure --with-ssl
- 7.10 Support DANE
  
- 8. GnuTLS
+ 8. POP3
- 8.1 SSL engine stuff
+ 8.1 Pipelining
- 8.3 check connection
+ 8.2 Enhanced capability support
  
- 9. SMTP
+ 9. IMAP
- 9.1 Specify the preferred authentication mechanism
+ 9.1 Enhanced capability support
- 9.2 Initial response
- 9.3 Pipelining
  
- 10. POP3
+ 10. LDAP
- 10.1 auth= in URLs
+ 10.1 SASL based authentication mechanisms
  
- 11. LDAP
+ 11. New protocols
- 11.1 SASL based authentication mechanisms
+ 11.1 RSYNC
 
- 12. Other protocols
+ 12. SSL
+ 12.1 Disable specific versions
+ 12.2 Provide mutex locking API
+ 12.3 Evaluate SSL patches
+ 12.4 Cache OpenSSL contexts
+ 12.5 Export session ids
+ 12.6 Provide callback for cert verification
+ 12.7 improve configure --with-ssl
+ 12.8 Support DANE
 
- 13. New protocols
+ 13. GnuTLS
- 13.1 RSYNC
+ 13.1 SSL engine stuff
+ 13.2 check connection
 
  14. SASL
  14.1 Other authentication mechanisms
@@ -85,9 +87,7 @@
  15.3 prevent file overwriting
  15.4 simultaneous parallel transfers
  15.5 provide formpost headers
- 15.6 url-specific options
+ 15.6 warning when setting an option
- 15.7 warning when setting an option
- 15.8 IPv6 addresses with globbing
 
  16. Build
  16.1 roffit
@@ -97,9 +97,10 @@
  17.2 nicer lacking perl message
  17.3 more protocols supported
  17.4 more platforms supported
+ 17.5 Add support for concurrent connections
 
  18. Next SONAME bump
- 18.1 http-style HEAD output for ftp
+ 18.1 http-style HEAD output for FTP
  18.2 combine error codes
  18.3 extend CURLOPT_SOCKOPTFUNCTION prototype
 
@@ -152,27 +153,41 @@
  we need libssh2 to properly tell us when we pass in a too small buffer and
  its current API (as of libssh2 1.2.7) doesn't.
 
-1.6 progress callback without doubles
+1.6 Modified buffer size approach
 
- The progress callback was introduced way back in the days and the choice to
+ Current libcurl allocates a fixed 16K size buffer for download and an
- use doubles in the arguments was possibly good at the time. Today the doubles
+ additional 16K for upload. They are always unconditionally part of the easy
- only confuse users and make the amounts less precise. We should introduce
+ handle. If CRLF translations are requested, an additional 32K "scratch
- another progress callback option that take precedence over the old one and
+ buffer" is allocated. A total of 64K transfer buffers in the worst case.
- have both co-exist for a forseeable time until we can remove the double-using
- one.
 
-1.7 Happy Eyeball dual stack connect
+ First, while the handles are not actually in use these buffers could be freed
+ so that lingering handles just kept in queues or whatever waste less memory.
 
- In order to make alternative technologies not suffer when transitioning, like
+ Secondly, SFTP is a protocol that needs to handle many ~30K blocks at once
- when introducing IPv6 as an alternative to IPv4 and there are more than one
+ since each need to be individually acked and therefore libssh2 must be
- option existing simultaneously there are reasons to reconsider internal
+ allowed to send (or receive) many separate ones in parallel to achieve high
- choices.
+ transfer speeds. A current libcurl build with a 16K buffer makes that
+ impossible, but one with a 512K buffer will reach MUCH faster transfers. But
+ allocating 512K unconditionally for all buffers just in case they would like
+ to do fast SFTP transfers at some point is not a good solution either.
 
- To make libcurl do blazing fast IPv6 in a dual-stack configuration, this needs
+ Dynamically allocate buffer size depending on protocol in use in combination
- to be addressed:
+ with freeing it after each individual transfer? Other suggestions?
 
-    http://tools.ietf.org/html/rfc6555
+1.7 Detect when called from within callbacks
 
+ We should set a state variable before calling callbacks, so that we
+ subsequently can add code within libcurl that returns error if called within
+ callbacks for when that's not supported.
+
+1.8 Allow SSL (HTTPS) to proxy
+
+ 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
+
+ ...and by Firefox soon:
+ https://bugzilla.mozilla.org/show_bug.cgi?id=378637
 
 2. libcurl - multi interface
 
@@ -198,18 +213,20 @@
 
 3. Documentation
 
-3.1  More and better
+3.1 Update date and version in man pages
 
- Exactly
+ 'maketgz' or another suitable script could update the .TH sections of the man
+ pages at release time to use the current date and curl/libcurl version
+ number.
 
 4. FTP
 
 4.1 HOST
 
- HOST is a suggested command in the works for a client to tell which host name
+ HOST is a command for a client to tell which host name to use, to offer FTP
- to use, to offer FTP servers named-based virtual hosting:
+ servers named-based virtual hosting:
 
- http://tools.ietf.org/html/draft-hethmon-mcmurray-ftp-hosts-11
+ http://tools.ietf.org/html/rfc7151
 
 4.2 Alter passive/active on failure and retry
 
@@ -220,7 +237,7 @@
 
 4.3 Earlier bad letter detection
 
- Make the detection of (bad) %0d and %0a codes in FTP url parts earlier in the
+ Make the detection of (bad) %0d and %0a codes in FTP URL parts earlier in the
  process to avoid doing a resolve and connect in vain.
 
 4.4 REST for large files
@@ -229,13 +246,7 @@
  the server doesn't set the pointer to the requested index. The tricky
  (impossible?) part is to figure out if the server did the right thing or not.
 
-4.5 FTP proxy support
+4.5 ASCII support
-
- Support the most common FTP proxies, Philip Newton provided a list allegedly
- from ncftp. This is not a subject without debate, and is probably not really
- suitable for libcurl.  http://curl.haxx.se/mail/archive-2003-04/0126.html
-
-4.6 ASCII support
 
  FTP ASCII transfers do not follow RFC959. They don't convert the data
  accordingly.
@@ -265,6 +276,25 @@
  headers use a default value so only headers that need to be moved have to be
  specified.
 
+5.4 SPDY
+
+ Chrome and Firefox already support SPDY and lots of web services do. There's
+ a library for us to use for this (spdylay) that has a similar API and the
+ same author as nghttp2.
+
+ spdylay: https://github.com/tatsuhiro-t/spdylay
+
+5.5 auth= in URLs
+
+ Add the ability to specify the preferred authentication mechanism to use by
+ using ;auth=<mech> in the login part of the URL.
+
+ For example:
+
+ http://test:pass;auth=NTLM@example.com would be equivalent to specifying --user
+ test:pass;auth=NTLM or --user test:pass --ntlm from the command line. 
+
+ Additionally this should be implemented for proxy base URLs as well.
 
 6. TELNET
 
@@ -290,35 +320,81 @@ to provide the data to send.
   use, but inefficient for any other.  Sent data should be sent in larger
   chunks.
 
-7. SSL
+7. SMTP
 
-7.1 Disable specific versions
+7.1 Pipelining
+
+ Add support for pipelining emails.
+
+7.2 Enhanced capability support
+
+ Add the ability, for an application that uses libcurl, to obtain the list of
+ capabilities returned from the EHLO command.
+
+8. POP3
+
+8.1 Pipelining
+
+ Add support for pipelining commands.
+
+8.2 Enhanced capability support
+
+ Add the ability, for an application that uses libcurl, to obtain the list of
+ capabilities returned from the CAPA command.
+
+9. IMAP
+
+9.1 Enhanced capability support
+
+ Add the ability, for an application that uses libcurl, to obtain the list of
+ capabilities returned from the CAPABILITY command.
+
+10. LDAP
+
+10.1 SASL based authentication mechanisms
+
+ Currently the LDAP module only supports ldap_simple_bind_s() in order to bind
+ to an LDAP server. However, this function sends username and password details
+ using the simple authentication mechanism (as clear text). However, it should
+ be possible to use ldap_bind_s() instead specifying the security context
+ information ourselves.
+
+11. New protocols
+
+11.1 RSYNC
+
+ There's no RFC for the protocol or an URI/URL format.  An implementation
+ should most probably use an existing rsync library, such as librsync.
+
+12. SSL
+
+12.1 Disable specific versions
 
  Provide an option that allows for disabling specific SSL versions, such as
  SSLv2 http://curl.haxx.se/bug/feature.cgi?id=1767276
 
-7.2 Provide mutex locking API
+12.2 Provide mutex locking API
 
  Provide a libcurl API for setting mutex callbacks in the underlying SSL
  library, so that the same application code can use mutex-locking
  independently of OpenSSL or GnutTLS being used.
 
-7.3 Evaluate SSL patches
+12.3 Evaluate SSL patches
 
  Evaluate/apply Gertjan van Wingerde's SSL patches:
  http://curl.haxx.se/mail/lib-2004-03/0087.html
 
-7.4 Cache OpenSSL contexts
+12.4 Cache OpenSSL contexts
 
  "Look at SSL cafile - quick traces look to me like these are done on every
- request as well, when they should only be necessary once per ssl context (or
+ request as well, when they should only be necessary once per SSL context (or
  once per handle)". The major improvement we can rather easily do is to make
  sure we don't create and kill a new SSL "context" for every request, but
  instead make one for every connection and re-use that SSL context in the same
  style connections are re-used. It will make us use slightly more memory but
  it will libcurl do less creations and deletions of SSL contexts.
 
-7.5 Export session ids
+12.5 Export session ids
 
  Add an interface to libcurl that enables "session IDs" to get
  exported/imported. Cris Bailiff said: "OpenSSL has functions which can
@@ -326,93 +402,45 @@ to provide the data to send.
  the state from such a buffer at a later date - this is used by mod_ssl for
  apache to implement and SSL session ID cache".
 
-7.6 Provide callback for cert verification
+12.6 Provide callback for cert verification
 
  OpenSSL supports a callback for customised verification of the peer
  certificate, but this doesn't seem to be exposed in the libcurl APIs. Could
  it be? There's so much that could be done if it were!
 
-7.7 Support other SSL libraries
+12.7 improve configure --with-ssl
-
- Make curl's SSL layer capable of using other free SSL libraries.  Such as
- MatrixSSL (http://www.matrixssl.org/).
-
-7.9 improve configure --with-ssl
 
  make the configure --with-ssl option first check for OpenSSL, then GnuTLS,
  then NSS...
 
-7.10 Support DANE
+12.8 Support DANE
 
  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
 
+ 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
+ approach. See Daniel's comments:
+ http://curl.haxx.se/mail/lib-2013-03/0103.html . libunbound may be the
+ correct library to base this development on.
 
-8. GnuTLS
+13. GnuTLS
 
-8.1 SSL engine stuff
+13.1 SSL engine stuff
 
  Is this even possible?
 
-8.3 check connection
+13.2 check connection
 
  Add a way to check if the connection seems to be alive, to correspond to the
  SSL_peak() way we use with OpenSSL.
 
-
-9. SMTP
-
-9.1 Specify the preferred authentication mechanism
-
- Add the ability to specify the preferred authentication mechanism or a list
- of mechanisms that should be used. Not only that, but the order that is
- returned by the server during the EHLO response should be honored by curl.
-
-9.2 Initial response
-
- Add the ability for the user to specify whether the initial response is
- included in the AUTH command. Some email servers, such as Microsoft
- Exchange, can work with either whilst others need to have the initial
- response sent separately:
-
- http://curl.haxx.se/mail/lib-2012-03/0114.html
-
-9.3 Pipelining
-
- Add support for pipelining emails.
-
-10. POP3
-
-10.1 auth= in URLs
-
- Being able to specify the preferred authentication mechanism in the URL as
- per RFC2384.
-
-11. LDAP
-
-11.1 SASL based authentication mechanisms
-
- Currently the LDAP module only supports ldap_simple_bind_s() in order to bind
- to an LDAP server. However, this function sends username and password details
- using the simple authentication mechanism (as clear text). However, it should
- be possible to use ldap_bind_s() instead specifing the security context
- information ourselves.
-
-12. Other protocols
-
-13. New protocols
-
-13.1 RSYNC
-
- There's no RFC for the protocol or an URI/URL format.  An implementation
- should most probably use an existing rsync library, such as librsync.
-
 14. SASL
 
 14.1 Other authentication mechanisms
 
- Add support for gssapi to SMTP, POP3 and IMAP.
+ Add support for GSSAPI to SMTP, POP3 and IMAP.
 
 15. Client
 
@@ -459,33 +487,12 @@ to provide the data to send.
  which should overwrite the program reasonable defaults (plain/text,
  8bit...)
 
-15.6 url-specific options
+15.6 warning when setting an option
-
- Provide a way to make options bound to a specific URL among several on the
- command line. Possibly by letting ':' separate options between URLs,
- similar to this:
-
-    curl --data foo --url url.com : \
-        --url url2.com : \
-        --url url3.com --data foo3
-
- (More details: http://curl.haxx.se/mail/archive-2004-07/0133.html)
-
- The example would do a POST-GET-POST combination on a single command line.
-
-15.7 warning when setting an option
 
   Display a warning when libcurl returns an error when setting an option.
   This can be useful to tell when support for a particular feature hasn't been
   compiled into the library.
 
-15.8 IPv6 addresses with globbing
-
-  Currently the command line client needs to get url globbing disabled (with
-  -g) for it to support IPv6 numerical addresses. This is a rather silly flaw
-  that should be corrected. It probably involves a smarter detection of the
-  '[' and ']' letters.
-
 16. Build
 
 16.1 roffit
@@ -508,7 +515,7 @@ to provide the data to send.
 
 17.3 more protocols supported
 
- Extend the test suite to include more protocols. The telnet could just do ftp
+ Extend the test suite to include more protocols. The telnet could just do FTP
  or http operations (for which we have test servers).
 
 17.4 more platforms supported
@@ -516,12 +523,26 @@ to provide the data to send.
  Make the test suite work on more platforms. OpenBSD and Mac OS. Remove
  fork()s and it should become even more portable.
 
+17.5 Add support for concurrent connections
+
+ Tests 836, 882 and 938 were designed to verify that separate connections aren't
+ used when using different login credentials in protocols that shouldn't re-use
+ a connection under such circumstances.
+
+ Unfortunately, ftpserver.pl doesn't appear to support multiple concurrent
+ connections. The read while() loop seems to loop until it receives a disconnect
+ from the client, where it then enters the waiting for connections loop. When
+ the client opens a second connection to the server, the first connection hasn't
+ been dropped (unless it has been forced - which we shouldn't do in these tests)
+ and thus the wait for connections loop is never entered to receive the second
+ connection.
+
 18. Next SONAME bump
 
-18.1 http-style HEAD output for ftp
+18.1 http-style HEAD output for FTP
 
  #undef CURL_FTP_HTTPSTYLE_HEAD in lib/ftp.c to remove the HTTP-style headers
- from being output in NOBODY requests over ftp
+ from being output in NOBODY requests over FTP
 
 18.2 combine error codes
 
@@ -555,7 +576,7 @@ to provide the data to send.
  for applications to differentiate on TCP vs UDP and even HTTP vs FTP and
  similar.
 
-10. Next major release
+19. Next major release
 
 19.1 cleanup return codes
 
@@ -619,7 +640,7 @@ to provide the data to send.
  but instead often restricts how the form functions can or can't be modified.
 
  Changing them to return a private handle will benefit the implementation and
- allow us much greater freedoms while still maintining a solid API and ABI.
+ allow us much greater freedoms while still maintaining a solid API and ABI.
 
 19.9 have form functions use CURL handle argument
 
@@ -633,7 +654,7 @@ to provide the data to send.
 
  Rather than use the URL to specify the mail client string to present in the
  HELO and EHLO commands, libcurl should support a new CURLOPT specifically for
- specifing this data as the URL is non-standard and to be honest a bit of a
+ specifying this data as the URL is non-standard and to be honest a bit of a
  hack ;-)
 
  Please see the following thread for more information:

docs/TheArtOfHttpScripting

@@ -1,16 +1,72 @@
-Online:  http://curl.haxx.se/docs/httpscripting.html
+Updated: Dec 24, 2013 (http://curl.haxx.se/docs/httpscripting.html)
-Date:    Jan 19, 2011
+                                  _   _ ____  _
+                              ___| | | |  _ \| |
+                             / __| | | | |_) | |
+                            | (__| |_| |  _ <| |___
+                             \___|\___/|_| \_\_____|
 
-                The Art Of Scripting HTTP Requests Using Curl
-                =============================================
 
- This document will assume that you're familiar with HTML and general
+The Art Of Scripting HTTP Requests Using Curl
- networking.
 
- The possibility to write scripts is essential to make a good computer
+ 1. HTTP Scripting
- system. Unix' capability to be extended by shell scripts and various tools to
+ 1.1 Background
- run various automated commands and scripts is one reason why it has succeeded
+ 1.2 The HTTP Protocol
- so well.
+ 1.3 See the Protocol
+ 1.4 See the Timing
+ 1.5 See the Response
+ 2. URL
+ 2.1 Spec
+ 2.2 Host
+ 2.3 Port number
+ 2.4 User name and password
+ 2.5 Path part
+ 3. Fetch a page
+ 3.1 GET
+ 3.2 HEAD
+ 4. HTML forms
+ 4.1 Forms explained
+ 4.2 GET
+ 4.3 POST
+ 4.4 File Upload POST
+ 4.5 Hidden Fields
+ 4.6 Figure Out What A POST Looks Like
+ 5. HTTP upload
+ 5.1 PUT
+ 6. HTTP Authentication
+ 6.1 Basic Authentication
+ 6.2 Other Authentication
+ 6.3 Proxy Authentication
+ 6.4 Hiding credentials
+ 7. More HTTP Headers
+ 7.1 Referer
+ 7.2 User Agent
+ 8. Redirects
+ 8.1 Location header
+ 8.2 Other redirects
+ 9. Cookies
+ 9.1 Cookie Basics
+ 9.2 Cookie options
+ 10. HTTPS
+ 10.1 HTTPS is HTTP secure
+ 10.2 Certificates
+ 11. Custom Request Elements
+ 11.1 Modify method and headers
+ 11.2 More on changed methods
+ 12. Web Login
+ 12.1 Some login tricks
+ 13. Debug
+ 13.1 Some debug tricks
+ 14. References
+ 14.1 Standards
+ 14.2 Sites
+
+==============================================================================
+
+1. HTTP Scripting
+
+ 1.1 Background
+
+ This document assumes that you're familiar with HTML and general networking.
 
  The increasing amount of applications moving to the web has made "HTTP
  Scripting" more frequently requested and wanted. To be able to automatically
@@ -27,7 +83,7 @@ Date:    Jan 19, 2011
  to glue everything together using some kind of script language or repeated
  manual invokes.
 
-1. The HTTP Protocol
+ 1.2 The HTTP Protocol
 
  HTTP is the protocol used to fetch data from web servers. It is a very simple
  protocol that is built upon TCP/IP. The protocol also allows information to
@@ -44,7 +100,7 @@ Date:    Jan 19, 2011
  well), response headers and most often also a response body. The "body" part
  is the plain data you requested, like the actual HTML or the image etc.
 
- 1.1 See the Protocol
+ 1.3 See the Protocol
 
   Using curl's option --verbose (-v as a short option) will display what kind
   of commands curl sends to the server, as well as a few other informational
@@ -59,13 +115,88 @@ Date:    Jan 19, 2011
 
       curl --trace-ascii debugdump.txt http://www.example.com/
 
+ 1.4 See the Timing
+
+  Many times you may wonder what exactly is taking all the time, or you just
+  want to know the amount of milliseconds between two points in a
+  transfer. For those, and other similar situations, the --trace-time option
+  is what you need. It'll prepend the time to each trace output line:
+
+      curl --trace-ascii d.txt --trace-time http://example.com/
+
+ 1.5 See the Response
+
+  By default curl sends the response to stdout. You need to redirect it
+  somewhere to avoid that, most often that is done with -o or -O.
+
 2. URL
 
+ 2.1 Spec
+
  The Uniform Resource Locator format is how you specify the address of a
  particular resource on the Internet. You know these, you've seen URLs like
- http://curl.haxx.se or https://yourbank.com a million times.
+ http://curl.haxx.se or https://yourbank.com a million times. RFC 3986 is the
+ canonical spec.
 
-3. GET a page
+ 2.2 Host
+
+ The host name is usually resolved using DNS or your /etc/hosts file to an IP
+ address and that's what curl will communicate with. Alternatively you specify
+ the IP address directly in the URL instead of a name.
+
+ For development and other trying out situation, you can point out a different
+ IP address for a host name than what would otherwise be used, by using curl's
+ --resolve option:
+
+      curl --resolve www.example.org:80:127.0.0.1 http://www.example.org/
+ 
+ 2.3 Port number
+
+ Each protocol curl supports operate on a default port number, be it over TCP
+ or in some cases UDP. Normally you don't have to take that into
+ consideration, but at times you run test servers on other ports or
+ similar. Then you can specify the port number in the URL with a colon and a
+ number immediately following the host name. Like when doing HTTP to port
+ 1234:
+
+      curl http://www.example.org:1234/
+
+ The port number you specify in the URL is the number that the server uses to
+ offer its services. Sometimes you may use a local proxy, and then you may
+ need to specify that proxy's port number separate on what curl needs to
+ connect to locally. Like when using a HTTP proxy on port 4321:
+
+      curl --proxy http://proxy.example.org:4321 http://remote.example.org/
+
+ 2.4 User name and password
+
+ Some services are setup to require HTTP authentication and then you need to
+ provide name and password which then is transferred to the remote site in
+ various ways depending on the exact authentication protocol used.
+
+ You can opt to either insert the user and password in the URL or you can
+ provide them separately:
+
+      curl http://user:password@example.org/
+
+ or
+
+      curl -u user:password http://example.org/
+
+ You need to pay attention that this kind of HTTP authentication is not what
+ is usually done and requested by user-oriented web sites these days. They
+ tend to use forms and cookies instead.
+
+ 2.5 Path part
+
+ The path part is just sent off to the server to request that it sends back
+ the associated response. The path is what is to the right side of the slash
+ that follows the host name and possibly port number.
+
+
+3. Fetch a page
+
+ 3.1 GET
 
  The simplest and most common request/operation made using HTTP is to get a
  URL. The URL could itself refer to a web page, an image or a file. The client
@@ -79,10 +210,23 @@ Date:    Jan 19, 2011
 
  All HTTP replies contain a set of response headers that are normally hidden,
  use curl's --include (-i) option to display them as well as the rest of the
- document. You can also ask the remote server for ONLY the headers by using
+ document.
- the --head (-I) option (which will make curl issue a HEAD request).
 
-4. Forms
+ 3.2 HEAD
+
+ You can ask the remote server for ONLY the headers by using the --head (-I)
+ option which will make curl issue a HEAD request. In some special cases
+ servers deny the HEAD method while others still work, which is a particular
+ kind of annoyance.
+
+ The HEAD method is defined and made so that the server returns the headers
+ exactly the way it would do for a GET, but without a body. It means that you
+ may see a Content-Length: in the response headers, but there must not be an
+ actual body in the HEAD response.
+
+4. HTML forms
+
+ 4.1 Forms explained
 
  Forms are the general way a web site can present a HTML page with fields for
  the user to enter data in, and then press some kind of 'OK' or 'submit'
@@ -95,7 +239,7 @@ Date:    Jan 19, 2011
  Of course there has to be some kind of program in the server end to receive
  the data you send. You cannot just invent something out of the air.
 
- 4.1 GET
+ 4.2 GET
 
   A GET-form uses the method GET, as specified in HTML like:
 
@@ -121,7 +265,7 @@ Date:    Jan 19, 2011
 
         curl "http://www.hotmail.com/when/junk.cgi?birthyear=1905&press=OK"
 
- 4.2 POST
+ 4.3 POST
 
   The GET method makes all input field names get displayed in the URL field of
   your browser. That's generally a good thing when you want to be able to
@@ -158,7 +302,7 @@ Date:    Jan 19, 2011
 
         curl --data-urlencode "name=I am Daniel" http://www.example.com
 
- 4.3 File Upload POST
+ 4.4 File Upload POST
 
   Back in late 1995 they defined an additional way to post data over HTTP. It
   is documented in the RFC 1867, why this method sometimes is referred to as
@@ -179,7 +323,7 @@ Date:    Jan 19, 2011
 
         curl --form upload=@localfilename --form press=OK [URL]
 
- 4.4 Hidden Fields
+ 4.5 Hidden Fields
 
   A very common way for HTML based application to pass state information
   between pages is to add hidden fields to the forms. Hidden fields are
@@ -200,7 +344,7 @@ Date:    Jan 19, 2011
 
         curl --data "birthyear=1905&press=OK&person=daniel" [URL]
 
- 4.5 Figure Out What A POST Looks Like
+ 4.6 Figure Out What A POST Looks Like
 
   When you're about fill in a form and send to a server by using curl instead
   of a browser, you're of course very interested in sending a POST exactly the
@@ -213,7 +357,9 @@ Date:    Jan 19, 2011
   You will then clearly see the data get appended to the URL, separated with a
   '?'-letter as GET forms are supposed to.
 
-5. PUT
+5. HTTP upload
+
+ 5.1 PUT
 
  The perhaps best way to upload data to a HTTP server is to use PUT. Then
  again, this of course requires that someone put a program or script on the
@@ -225,6 +371,8 @@ Date:    Jan 19, 2011
 
 6. HTTP Authentication
 
+ 6.1 Basic Authentication
+
  HTTP Authentication is the ability to tell the server your username and
  password so that it can verify that you're allowed to do the request you're
  doing. The Basic authentication used in HTTP (which is the type curl uses by
@@ -236,10 +384,14 @@ Date:    Jan 19, 2011
 
         curl --user name:password http://www.example.com
 
+ 6.2 Other Authentication
+
  The site might require a different authentication method (check the headers
  returned by the server), and then --ntlm, --digest, --negotiate or even
  --anyauth might be options that suit you.
 
+ 6.3 Proxy Authentication
+
  Sometimes your HTTP access is only available through the use of a HTTP
  proxy. This seems to be especially common at various companies. A HTTP proxy
  may require its own user and password to allow the client to get through to
@@ -253,6 +405,8 @@ Date:    Jan 19, 2011
  If you use any one these user+password options but leave out the password
  part, curl will prompt for the password interactively.
 
+ 6.4 Hiding credentials
+
  Do note that when a program is run, its parameters might be possible to see
  when listing the running processes of the system. Thus, other users may be
  able to watch your passwords if you pass them as plain command line
@@ -262,7 +416,9 @@ Date:    Jan 19, 2011
  many web sites will not use this concept when they provide logins etc. See
  the Web Login chapter further below for more details on that.
 
-7. Referer
+7. More HTTP Headers
+
+ 7.1 Referer
 
  A HTTP request may include a 'referer' field (yes it is misspelled), which
  can be used to tell from which URL the client got to this particular
@@ -276,7 +432,7 @@ Date:    Jan 19, 2011
 
         curl --referer http://www.example.come http://www.example.com
 
-8. User Agent
+ 7.2 User Agent
 
  Very similar to the referer field, all HTTP requests may set the User-Agent
  field. It names what user agent (client) that is being used. Many
@@ -298,7 +454,9 @@ Date:    Jan 19, 2011
 
   curl --user-agent "Mozilla/4.73 [en] (X11; U; Linux 2.2.15 i686)" [URL]
 
-9. Redirects
+8. Redirects
+
+ 8.1 Location header
 
  When a resource is requested from a server, the reply from the server may
  include a hint about where the browser should go next to find this page, or a
@@ -318,7 +476,16 @@ Date:    Jan 19, 2011
  only use POST in the first request, and then revert to GET in the following
  operations.
 
-10. Cookies
+ 8.2 Other redirects
+
+ Browser typically support at least two other ways of redirects that curl
+ doesn't: first the html may contain a meta refresh tag that asks the browser
+ to load a specific URL after a set number of seconds, or it may use
+ javascript to do it.
+
+9. Cookies
+
+ 9.1 Cookie Basics
 
  The way the web browsers do "client side state control" is by using
  cookies. Cookies are just names with associated contents. The cookies are
@@ -335,6 +502,8 @@ Date:    Jan 19, 2011
  must be able to record and send back cookies the way the web application
  expects them. The same way browsers deal with them.
 
+ 9.2 Cookie options
+
  The simplest way to send a few cookies to the server when getting a page with
  curl is to add them on the command line like:
 
@@ -351,7 +520,7 @@ Date:    Jan 19, 2011
 
  Curl has a full blown cookie parsing engine built-in that comes to use if you
  want to reconnect to a server and use cookies that were stored from a
- previous connection (or handicrafted manually to fool the server into
+ previous connection (or hand-crafted manually to fool the server into
  believing you had a previous connection). To use previously stored cookies,
  you run curl like:
 
@@ -366,16 +535,18 @@ Date:    Jan 19, 2011
         curl --cookie nada --location http://www.example.com
 
  Curl has the ability to read and write cookie files that use the same file
- format that Netscape and Mozilla do. It is a convenient way to share cookies
+ format that Netscape and Mozilla once used. It is a convenient way to share
- between browsers and automatic scripts. The --cookie (-b) switch
+ cookies between scripts or invokes. The --cookie (-b) switch automatically
- automatically detects if a given file is such a cookie file and parses it,
+ detects if a given file is such a cookie file and parses it, and by using the
- and by using the --cookie-jar (-c) option you'll make curl write a new cookie
+ --cookie-jar (-c) option you'll make curl write a new cookie file at the end
- file at the end of an operation:
+ of an operation:
 
         curl --cookie cookies.txt --cookie-jar newcookies.txt \
         http://www.example.com
 
-11. HTTPS
+10. HTTPS
+
+ 10.1 HTTPS is HTTP secure
 
  There are a few ways to do secure HTTP transfers. The by far most common
  protocol for doing this is what is generally known as HTTPS, HTTP over
@@ -391,7 +562,7 @@ Date:    Jan 19, 2011
 
         curl https://secure.example.com
 
- 11.1 Certificates
+ 10.2 Certificates
 
   In the HTTPS world, you use certificates to validate that you are the one
   you claim to be, as an addition to normal passwords. Curl supports client-
@@ -413,7 +584,9 @@ Date:    Jan 19, 2011
 
         http://curl.haxx.se/docs/sslcerts.html
 
-12. Custom Request Elements
+11. Custom Request Elements
+
+11.1 Modify method and headers
 
  Doing fancy stuff, you may need to add or change elements of a single curl
  request.
@@ -434,7 +607,26 @@ Date:    Jan 19, 2011
 
         curl --header "Destination: http://nowhere" http://example.com
 
-13. Web Login
+ 11.2 More on changed methods
+
+ It should be noted that curl selects which methods to use on its own
+ depending on what action to ask for. -d will do POST, -I will do HEAD and so
+ on. If you use the --request / -X option you can change the method keyword
+ curl selects, but you will not modify curl's behavior. This means that if you
+ for example use -d "data" to do a POST, you can modify the method to a
+ PROPFIND with -X and curl will still think it sends a POST. You can change
+ the normal GET to a POST method by simply adding -X POST in a command line
+ like:
+
+        curl -X POST http://example.org/
+
+ ... but curl will still think and act as if it sent a GET so it won't send any
+ request body etc.
+
+
+12. Web Login
+
+ 12.1 Some login tricks
 
  While not strictly just HTTP related, it still cause a lot of people problems
  so here's the executive run-down of how the vast majority of all login forms
@@ -453,7 +645,7 @@ Date:    Jan 19, 2011
  sometimes they use such code to set or modify cookie contents. Possibly they
  do that to prevent programmed logins, like this manual describes how to...
  Anyway, if reading the code isn't enough to let you repeat the behavior
- manually, capturing the HTTP requests done by your browers and analyzing the
+ manually, capturing the HTTP requests done by your browsers and analyzing the
  sent cookies is usually a working method to work out how to shortcut the
  javascript need.
 
@@ -463,7 +655,9 @@ Date:    Jan 19, 2011
  to do a proper login POST. Remember that the contents need to be URL encoded
  when sent in a normal POST.
 
-14. Debug
+13. Debug
+
+ 13.1 Some debug tricks
 
  Many times when you run curl on a site, you'll notice that the site doesn't
  seem to respond the same way to your curl requests as it does to your
@@ -473,35 +667,40 @@ Date:    Jan 19, 2011
  browser's requests:
 
  * Use the --trace-ascii option to store fully detailed logs of the requests
-   for easier analyzing and better understanding
+ for easier analyzing and better understanding
 
  * Make sure you check for and use cookies when needed (both reading with
-   --cookie and writing with --cookie-jar)
+ --cookie and writing with --cookie-jar)
 
  * Set user-agent to one like a recent popular browser does
 
  * Set referer like it is set by the browser
 
  * If you use POST, make sure you send all the fields and in the same order as
-   the browser does it. (See chapter 4.5 above)
+ the browser does it.
 
  A very good helper to make sure you do this right, is the LiveHTTPHeader tool
  that lets you view all headers you send and receive with Mozilla/Firefox
- (even when using HTTPS).
+ (even when using HTTPS). Chrome features similar functionality out of the box
+ among the developer's tools.
 
  A more raw approach is to capture the HTTP traffic on the network with tools
  such as ethereal or tcpdump and check what headers that were sent and
  received by the browser. (HTTPS makes this technique inefficient.)
 
-15. References
+14. References
+
+ 14.1 Standards
 
  RFC 2616 is a must to read if you want in-depth understanding of the HTTP
- protocol.
+ protocol
 
- RFC 3986 explains the URL syntax.
+ RFC 3986 explains the URL syntax
 
- RFC 2109 defines how cookies are supposed to work.
+ RFC 1867 defines the HTTP post upload format
 
- RFC 1867 defines the HTTP post upload format.
+ RFC 6525 defines how HTTP cookies work
+
+ 14.2 Sites
 
  http://curl.haxx.se is the home of the cURL project

docs/curl.1

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, 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
@@ -103,6 +103,18 @@ any response data to the terminal.
 If you prefer a progress "bar" instead of the regular meter, \fI-#\fP is your
 friend.
 .SH OPTIONS
+Options start with one or two dashes. Many of the options require an addition
+value next to it.
+
+The short "single-dash" form of the options, -d for example, may be used with
+or without a space between it and its value, although a space is a recommended
+separator. The long "double-dash" form, --data for example, requires a space
+between it and its value.
+
+Short version options that don't need any additional values can be used
+immediately next to each other, like for example you can specify all the
+options -O, -L and -v at once as -OLv.
+
 In general, all boolean options are enabled with --\fBoption\fP and yet again
 disabled with --\fBno-\fPoption. That is, you use the exact same option name
 but prefix it with "no-". However, in this list we mostly only list and show
@@ -112,12 +124,38 @@ same command line option.)
 .IP "-#, --progress-bar"
 Make curl display progress as a simple progress bar instead of the standard,
 more informational, meter.
+.IP "-:, --next"
+Tells curl to use a separate operation for the following URL and associated
+options. This allows you to send several URL requests, each with their own
+specific options, for example, such as different user names or custom requests
+for each. (Added in 7.36.0)
 .IP "-0, --http1.0"
-(HTTP) Forces curl to issue its requests using HTTP 1.0 instead of using its
+(HTTP) Tells curl to use HTTP version 1.0 instead of using its internally
-internally preferred: HTTP 1.1.
+preferred: HTTP 1.1.
+.IP "--http1.1"
+(HTTP) Tells curl to use HTTP version 1.1. This is the internal default
+version. (Added in 7.33.0)
+.IP "--http2"
+(HTTP) Tells curl to issue its requests using HTTP 2. This requires that the
+underlying libcurl was built to support it. (Added in 7.33.0)
+.IP "--no-npn"
+Disable the NPN TLS extension. NPN is enabled by default if libcurl was built
+with an SSL library that supports NPN. NPN is used by a libcurl that supports
+HTTP 2 to negotiate HTTP 2 support with the server during https sessions.
+
+(Added in 7.36.0)
+.IP "--no-alpn"
+Disable the ALPN TLS extension. ALPN is enabled by default if libcurl was built
+with an SSL library that supports ALPN. ALPN is used by a libcurl that supports
+HTTP 2 to negotiate HTTP 2 support with the server during https sessions.
+
+(Added in 7.36.0)
 .IP "-1, --tlsv1"
 (SSL)
-Forces curl to use TLS version 1 when negotiating with a remote TLS server.
+Forces curl to use TLS version 1.x when negotiating with a remote TLS server.
+You can use options \fI--tlsv1.0\fP, \fI--tlsv1.1\fP, and \fI--tlsv1.2\fP to
+control the TLS version more precisely (if the SSL backend in use supports such
+a level of control).
 .IP "-2, --sslv2"
 (SSL)
 Forces curl to use SSL version 2 when negotiating with a remote SSL server.
@@ -230,7 +268,9 @@ server sends an unsupported encoding, curl will report an error.
 .IP "--connect-timeout <seconds>"
 Maximum time in seconds that you allow the connection to the server to take.
 This only limits the connection phase, once curl has connected this option is
-of no more use. See also the \fI-m, --max-time\fP option.
+of no more use.  Since 7.32.0, this option accepts decimal values, but the
+actual timeout will decrease in accuracy as the specified timeout increases in
+decimal precision. See also the \fI-m, --max-time\fP option.
 
 If this option is used several times, the last one will be used.
 .IP "--create-dirs"
@@ -267,10 +307,11 @@ data pieces specified will be merged together with a separating
 chunk that looks like \&'name=daniel&skill=lousy'.
 
 If you start the data with the letter @, the rest should be a file name to
-read the data from, or - if you want curl to read the data from stdin.  The
+read the data from, or - if you want curl to read the data from
-contents of the file must already be URL-encoded. Multiple files can also be
+stdin. Multiple files can also be specified. Posting data from a file
-specified. Posting data from a file named 'foobar' would thus be done with
+named 'foobar' would thus be done with \fI--data\fP @foobar. When --data is
-\fI--data @foobar\fP.
+told to read from a file like that, carriage returns and newlines will be
+stripped out.
 .IP "-D, --dump-header <file>"
 Write the protocol headers to the specified file.
 
@@ -292,7 +333,7 @@ whatsoever.
 
 If you start the data with the letter @, the rest should be a filename.  Data
 is posted in a similar manner as \fI--data-ascii\fP does, except that newlines
-are preserved and conversions are never done.
+and carriage returns are preserved and conversions are never done.
 
 If this option is used several times, the ones following the first will append
 data as described in \fI-d, --data\fP.
@@ -367,8 +408,41 @@ is an alias for \fB--disable-epsv\fP.
 
 Disabling EPSV only changes the passive behavior. If you want to switch to
 active mode you need to use \fI-P, --ftp-port\fP.
+.IP "--dns-interface <interface>"
+Tell curl to send outgoing DNS requests through <interface>. This option
+is a counterpart to \fI--interface\fP (which does not affect DNS). The
+supplied string must be an interface name (not an address).
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one. (Added in
+7.33.0)
+.IP "--dns-ipv4-addr <ip-address>"
+Tell curl to bind to <ip-address> when making IPv4 DNS requests, so that
+the DNS requests originate from this address. The argument should be a
+single IPv4 address.
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.  (Added in
+7.33.0)
+.IP "--dns-ipv6-addr <ip-address>"
+Tell curl to bind to <ip-address> when making IPv6 DNS requests, so that
+the DNS requests originate from this address. The argument should be a
+single IPv6 address.
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.  (Added in
+7.33.0)
+.IP "--dns-servers <ip-address,ip-address>"
+Set the list of DNS servers to be used instead of the system default.
+The list of IP addresses should be separated with commas. Port numbers
+may also optionally be given as \fI:<port-number>\fP after each IP
+address.
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.  (Added in
+7.33.0)
 .IP "-e, --referer <URL>"
-(HTTP) Sends the "Referer Page" information to the HTTP server. This can also
+(HTTP) Sends the "Referrer Page" information to the HTTP server. This can also
 be set with the \fI-H, --header\fP flag of course.  When used with
 \fI-L, --location\fP you can append ";auto" to the --referer URL to make curl
 automatically set the previous URL when it follows a Location: header. The
@@ -378,7 +452,8 @@ If this option is used several times, the last one will be used.
 .IP "-E, --cert <certificate[:password]>"
 (SSL) Tells curl to use the specified client certificate file when getting a
 file with HTTPS, FTPS or another SSL-based protocol. The certificate must be
-in PEM format.  If the optional password isn't specified, it will be queried
+in PKCS#12 format if using Secure Transport, or PEM format if using any other
+engine.  If the optional password isn't specified, it will be queried
 for on the terminal. Note that this option assumes a \&"certificate" file that
 is the private key and the private certificate concatenated! See \fI--cert\fP
 and \fI--key\fP to specify them independently.
@@ -388,7 +463,16 @@ curl the nickname of the certificate to use within the NSS database defined
 by the environment variable SSL_DIR (or by default /etc/pki/nssdb). If the
 NSS PEM PKCS#11 module (libnsspem.so) is available then PEM files may be
 loaded. If you want to use a file from the current directory, please precede
-it with "./" prefix, in order to avoid confusion with a nickname.
+it with "./" prefix, in order to avoid confusion with a nickname.  If the
+nickname contains ":", it needs to be preceded by "\\" so that it is not
+recognized as password delimiter.  If the nickname contains "\\", it needs to
+be escaped as "\\\\" so that it is not recognized as an escape character.
+
+(iOS and Mac OS X only) If curl is built against Secure Transport, then the
+certificate string can either be the name of a certificate/private key in the
+system or user keychain, or the path to a PKCS#12-encoded certificate and
+private key. If you want to use a file from the current directory, please
+precede it with "./" prefix, in order to avoid confusion with a nickname.
 
 If this option is used several times, the last one will be used.
 .IP "--engine <name>"
@@ -582,10 +666,10 @@ you can specify URLs that contain the letters {}[] without having them being
 interpreted by curl itself. Note that these letters are not normal legal URL
 contents but they should be encoded according to the URI standard.
 .IP "-G, --get"
-When used, this option will make all data specified with \fI-d, --data\fP or
+When used, this option will make all data specified with \fI-d, --data\fP,
-\fI--data-binary\fP to be used in an HTTP GET request instead of the POST
+\fI--data-binary\fP or \fI--data-urlencode\fP to be used in an HTTP GET
-request that otherwise would be used. The data will be appended to the URL
+request instead of the POST request that otherwise would be used. The data
-with a '?' separator.
+will be appended to the URL with a '?' separator.
 
 If used in combination with -I, the POST data will instead be appended to the
 URL with a HEAD request.
@@ -594,16 +678,16 @@ If this option is used several times, only the first one is used. This is
 because undoing a GET doesn't make sense, but you should then instead enforce
 the alternative method you prefer.
 .IP "-H, --header <header>"
-(HTTP) Extra header to use when getting a web page. You may specify any number
+(HTTP) Extra header to include in the request when sending HTTP to a
-of extra headers. Note that if you should add a custom header that has the
+server. You may specify any number of extra headers. Note that if you should
-same name as one of the internal ones curl would use, your externally set
+add a custom header that has the same name as one of the internal ones curl
-header will be used instead of the internal one. This allows you to make even
+would use, your externally set header will be used instead of the internal
-trickier stuff than curl would normally do. You should not replace internally
+one. This allows you to make even trickier stuff than curl would normally
-set headers without knowing perfectly well what you're doing. Remove an
+do. You should not replace internally set headers without knowing perfectly
-internal header by giving a replacement without content on the right side of
+well what you're doing. Remove an internal header by giving a replacement
-the colon, as in: -H \&"Host:". If you send the custom header with no-value
+without content on the right side of the colon, as in: -H \&"Host:". If you
-then its header must be terminated with a semicolon, such as \-H
+send the custom header with no-value then its header must be terminated with a
-\&"X-Custom-Header;" to send "X-Custom-Header:".
+semicolon, such as \-H \&"X-Custom-Header;" to send "X-Custom-Header:".
 
 curl will make sure that each header you add/replace is sent with the proper
 end-of-line marker, you should thus \fBnot\fP add that as a part of the header
@@ -612,6 +696,9 @@ for you.
 
 See also the \fI-A, --user-agent\fP and \fI-e, --referer\fP options.
 
+Starting in 7.37.0, you need \fI--proxy-header\fP to send custom headers
+intended for a proxy.
+
 This option can be used multiple times to add/replace/remove multiple headers.
 .IP "--hostpubmd5 <md5>"
 (SCP/SFTP) Pass a string containing 32 hexadecimal digits. The string should
@@ -647,6 +734,9 @@ cookies when they're closed down.
 (HTTP) This option tells the \fI-O, --remote-name\fP option to use the
 server-specified Content-Disposition filename instead of extracting a filename
 from the URL.
+
+There's no attempt to decode %-sequences (yet) in the provided file name, so
+this option may provide you with rather unexpected file names.
 .IP "-k, --insecure"
 (SSL) This option explicitly allows curl to perform "insecure" SSL connections
 and transfers. All SSL connections are attempted to be made secure by using
@@ -658,16 +748,21 @@ See this online resource for further details:
 .IP "-K, --config <config file>"
 Specify which config file to read curl arguments from. The config file is a
 text file in which command line arguments can be written which then will be
-used as if they were written on the actual command line. Options and their
+used as if they were written on the actual command line.
-parameters must be specified on the same config file line, separated by
+
-whitespace, colon, the equals sign or any combination thereof (however,
+Options and their parameters must be specified on the same config file line,
-the preferred separator is the equals sign). If the parameter is to contain
+separated by whitespace, colon, or the equals sign. Long option names can
-whitespace, the parameter must be enclosed within quotes. Within double
+optionally be given in the config file without the initial double dashes and
-quotes, the following escape sequences are available: \\\\, \\", \\t, \\n,
+if so, the colon or equals characters can be used as separators. If the option
-\\r and \\v. A backslash preceding any other letter is ignored. If the
+is specified with one or two dashes, there can be no colon or equals character
-first column of a config line is a '#' character, the rest of the line will be
+between the option and its parameter.
-treated as a comment. Only write one option per physical line in the config
+
-file.
+If the parameter is to contain whitespace, the parameter must be enclosed
+within quotes. Within double quotes, the following escape sequences are
+available: \\\\, \\", \\t, \\n, \\r and \\v. A backslash preceding any other
+letter is ignored. If the first column of a config line is a '#' character,
+the rest of the line will be treated as a comment. Only write one option per
+physical line in the config file.
 
 Specify the filename to -K, --config as '-' to make curl read the file from
 stdin.
@@ -678,9 +773,6 @@ line. So, it could look similar to this:
 
 url = "http://curl.haxx.se/docs/"
 
-Long option names can optionally be given in the config file without the
-initial double dashes.
-
 When curl is invoked, it always (unless \fI-q\fP is used) checks for a default
 config file and uses it if found. The default config file is checked for in
 the following places in this order:
@@ -742,15 +834,23 @@ see if your curl supports it.
 If this option is used several times, the last one will be used.
 .IP "-l, --list-only"
 (FTP)
-When listing an FTP directory, this switch forces a name-only view.
+When listing an FTP directory, this switch forces a name-only view. This is
-Especially useful if you want to machine-parse the contents of an FTP
+especially useful if the user wants to machine-parse the contents of an FTP
-directory since the normal directory view doesn't use a standard look
+directory since the normal directory view doesn't use a standard look or
-or format.
+format. When used like this, the option causes a NLST command to be sent to
+the server instead of LIST.
 
-This option causes an FTP NLST command to be sent.  Some FTP servers
+Note: Some FTP servers list only files in their response to NLST; they do not
-list only files in their response to NLST; they do not include
+include sub-directories and symbolic links.
-subdirectories and symbolic links.
 
+(POP3)
+When retrieving a specific email from POP3, this switch forces a LIST command
+to be performed instead of RETR. This is particularly useful if the user wants
+to see if a specific message id exists on the server and what size it is.
+
+Note: When combined with \fI-X, --request <command>\fP, this option can be used
+to send an UIDL command instead, so the user may use the email's unique
+identifier rather than it's message id to make the request. (Added in 7.21.5)
 .IP "-L, --location"
 (HTTP/HTTPS) If the server reports that the requested page has moved to a
 different location (indicated with a Location: header and a 3XX response code),
@@ -805,7 +905,20 @@ Basic authentication).
 .IP "-m, --max-time <seconds>"
 Maximum time in seconds that you allow the whole operation to take.  This is
 useful for preventing your batch jobs from hanging for hours due to slow
-networks or links going down.  See also the \fI--connect-timeout\fP option.
+networks or links going down.  Since 7.32.0, this option accepts decimal
+values, but the actual timeout will decrease in accuracy as the specified
+timeout increases in decimal precision.  See also the \fI--connect-timeout\fP
+option.
+
+If this option is used several times, the last one will be used.
+.IP "--login-options <options>"
+Specify the login options to use during server authentication.
+
+You can use the login options to specify protocol specific options that may
+be used during authentication. At present only IMAP, POP3 and SMTP support
+login options. For more information about the login options please see
+RFC 2384, RFC 5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in
+7.34.0).
 
 If this option is used several times, the last one will be used.
 .IP "--mail-auth <address>"
@@ -827,10 +940,18 @@ return with exit code 63.
 files this option has no effect even if the file transfer ends up being larger
 than this given limit. This concerns both FTP and HTTP transfers.
 .IP "--mail-rcpt <address>"
-(SMTP) Specify a single address that the given mail should get sent to. This
+(SMTP) Specify a single address, user name or mailing list name.
-option can be used multiple times to specify many recipients.
 
-(Added in 7.20.0)
+When performing a mail transfer, the recipient should specify a valid email
+address to send the mail to. (Added in 7.20.0)
+
+When performing an address verification (VRFY command), the recipient should be
+specified as the user name or user name and domain (as per Section 3.5 of
+RFC5321). (Added in 7.34.0)
+
+When performing a mailing list expand (EXPN command), the recipient should be
+specified using the mailing list name, such as "Friends" or "London-Office".
+(Added in 7.34.0)
 .IP "--max-redirs <num>"
 Set maximum number of redirection-followings allowed. If \fI-L, --location\fP
 is used, this option can be used to prevent curl from following redirections
@@ -986,7 +1107,37 @@ Consequentially, the file will be saved in the current working directory. If
 you want the file saved in a different directory, make sure you change current
 working directory before you invoke curl with the \fB-O, --remote-name\fP flag!
 
+There is no URL decoding done on the file name. If it has %20 or other URL
+encoded parts of the name, they will end up as-is as file name.
+
 You may use this option as many times as the number of URLs you have.
+.IP "--oauth2-bearer"
+(IMAP, POP3, SMTP)
+Specify the Bearer Token for OAUTH 2.0 server authentication. The Bearer Token
+is used in conjunction with the user name which can be specified as part of the
+\fI--url\fP or \fI-u, --user\fP options.
+
+The Bearer Token and user name are formatted according to RFC 6750.
+
+If this option is used several times, the last one will be used.
+.IP "--proxy-header <header>"
+(HTTP) Extra header to include in the request when sending HTTP to a
+proxy. You may specify any number of extra headers. This is the equivalent
+option to \fI-H, --header\fP but is for proxy communication only like in
+CONNECT requests when you want a separate header sent to the proxy to what is
+sent to the actual remote host.
+
+curl will make sure that each header you add/replace is sent with the proper
+end-of-line marker, you should thus \fBnot\fP add that as a part of the header
+content: do not add newlines or carriage returns, they will only mess things
+up for you.
+
+Headers specified with this option will not be included in requests that curl
+knows will not be sent to a proxy.
+
+This option can be used multiple times to add/replace/remove multiple headers.
+
+(Added in 7.37.0)
 .IP "-p, --proxytunnel"
 When an HTTP proxy is used (\fI-x, --proxy\fP), this option will cause non-HTTP
 protocols to attempt to tunnel through the proxy instead of merely using it to
@@ -1038,6 +1189,13 @@ ubiquitous in web browsers, so curl does the conversion by default to maintain
 consistency. However, a server may require a POST to remain a POST after such
 a redirection. This option is meaningful only when using \fI-L, --location\fP
 (Added in 7.19.1)
+.IP "--post303"
+(HTTP) Tells curl to respect RFC 2616/10.3.2 and not convert POST requests
+into GET requests when following a 303 redirection. The non-RFC behaviour is
+ubiquitous in web browsers, so curl does the conversion by default to maintain
+consistency. However, a server may require a POST to remain a POST after such
+a redirection. This option is meaningful only when using \fI-L, --location\fP
+(Added in 7.26.0)
 .IP "--proto <protocols>"
 Tells curl to use the listed protocols for its initial retrieval. Protocols
 are evaluated left to right, are comma separated, and are each a protocol
@@ -1272,8 +1430,12 @@ Set this option to zero to not timeout retries. (Added in 7.12.3)
 
 If this option is used several times, the last one will be used.
 .IP "-s, --silent"
-Silent or quiet mode. Don't show progress meter or error messages.  Makes
+Silent or quiet mode. Don't show progress meter or error messages.  Makes Curl
-Curl mute.
+mute. It will still output the data you ask for, potentially even to the
+terminal/stdout unless you redirect it.
+.IP "--sasl-ir"
+Enable initial response in SASL authentication.
+(Added in 7.31.0)
 .IP "-S, --show-error"
 When used with \fI-s\fP it makes curl show an error message if it fails.
 .IP "--ssl"
@@ -1293,7 +1455,7 @@ option name can still be used but will be removed in a future version.
 .IP "--ssl-allow-beast"
 (SSL) This option tells curl to not work around a security flaw in the SSL3
 and TLS1.0 protocols known as BEAST.  If this option isn't used, the SSL layer
-may use work-arounds known to cause interoperability problems with some older
+may use workarounds known to cause interoperability problems with some older
 SSL implementations. WARNING: this option loosens the SSL security, and by
 using this flag you ask for exactly that.  (Added in 7.25.0)
 .IP "--socks4 <host[:port]>"
@@ -1412,14 +1574,26 @@ Set TLS authentication type. Currently, the only supported option is "SRP",
 for TLS-SRP (RFC 5054). If \fI--tlsuser\fP and \fI--tlspassword\fP are
 specified but \fI--tlsauthtype\fP is not, then this option defaults to "SRP".
 (Added in 7.21.4)
-.IP "--tlsuser <user>"
-Set username for use with the TLS authentication method specified with
-\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also be set.  (Added in
-7.21.4)
 .IP "--tlspassword <password>"
 Set password for use with the TLS authentication method specified with
 \fI--tlsauthtype\fP. Requires that \fI--tlsuser\fP also be set.  (Added in
 7.21.4)
+.IP "--tlsuser <user>"
+Set username for use with the TLS authentication method specified with
+\fI--tlsauthtype\fP. Requires that \fI--tlspassword\fP also be set.  (Added in
+7.21.4)
+.IP "--tlsv1.0"
+(SSL)
+Forces curl to use TLS version 1.0 when negotiating with a remote TLS server.
+(Added in 7.34.0)
+.IP "--tlsv1.1"
+(SSL)
+Forces curl to use TLS version 1.1 when negotiating with a remote TLS server.
+(Added in 7.34.0)
+.IP "--tlsv1.2"
+(SSL)
+Forces curl to use TLS version 1.2 when negotiating with a remote TLS server.
+(Added in 7.34.0)
 .IP "--tr-encoding"
 (HTTP) Request a compressed Transfer-Encoding response using one of the
 algorithms curl supports, and uncompress the data while receiving it.
@@ -1453,12 +1627,11 @@ Prepends a time stamp to each trace or verbose line that curl displays.
 Specify the user name and password to use for server authentication. Overrides
 \fI-n, --netrc\fP and \fI--netrc-optional\fP.
 
-If you just give the user name (without entering a colon) curl will prompt for
+If you simply specify the user name, curl will prompt for a password.
-a password.
 
-If you use an SSPI-enabled curl binary and do NTLM authentication, you can
+If you use an SSPI-enabled curl binary and perform NTLM authentication, you
-force curl to pick up the user name and password from your environment by
+can force curl to select the user name and password from your environment by
-simply specifying a single colon with this option: "-u :".
+specifying a single colon with this option: "-u :".
 
 If this option is used several times, the last one will be used.
 .IP "-U, --proxy-user <user:password>"
@@ -1619,8 +1792,16 @@ to follow location: headers.
 
 If this option is used several times, the last one will be used.
 .IP "-x, --proxy <[protocol://][user:password@]proxyhost[:port]>"
-Use the specified HTTP proxy. If the port number is not specified, it is
+Use the specified proxy.
-assumed at port 1080.
+
+The proxy string can be specified with a protocol:// prefix to specify
+alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
+socks5h:// to request the specific SOCKS version to be used. No protocol
+specified, http:// and all others will be treated as HTTP proxies. (The
+protocol support was added in curl 7.21.7)
+
+If the port number is not specified in the proxy string, it is assumed to be
+1080.
 
 This option overrides existing environment variables that set the proxy to
 use. If there's an environment variable setting a proxy, you can set proxy to
@@ -1639,11 +1820,6 @@ The proxy host can be specified the exact same way as the proxy environment
 variables, including the protocol prefix (http://) and the embedded user +
 password.
 
-From 7.21.7, the proxy string may be specified with a protocol:// prefix to
-specify alternative proxy protocols. Use socks4://, socks4a://, socks5:// or
-socks5h:// to request the specific SOCKS version to be used. No protocol
-specified, http:// and all others will be treated as HTTP proxies.
-
 If this option is used several times, the last one will be used.
 .IP "-X, --request <command>"
 (HTTP) Specifies a custom request method to use when communicating with the
@@ -1665,11 +1841,20 @@ option.
 Specifies a custom FTP command to use instead of LIST when doing file lists
 with FTP.
 
-If this option is used several times, the last one will be used.
+(POP3)
+Specifies a custom POP3 command to use instead of LIST or RETR. (Added in
+7.26.0)
 
+(IMAP)
+Specifies a custom IMAP command to use instead of LIST. (Added in 7.30.0)
+
+(SMTP)
+Specifies a custom SMTP command to use instead of HELP or VRFY. (Added in 7.34.0)
+
+If this option is used several times, the last one will be used.
 .IP "--xattr"
 When saving output to a file, this option tells curl to store certain file
-metadata in extened file attributes. Currently, the URL is stored in the
+metadata in extended file attributes. Currently, the URL is stored in the
 xdg.origin.url attribute and, for HTTP, the content type is stored in
 the mime_type attribute. If the file system does not support extended
 attributes, a warning is issued.
@@ -1689,7 +1874,7 @@ speed-time seconds it gets aborted. speed-time is set with \fI-y\fP and is 30
 if not set.
 
 If this option is used several times, the last one will be used.
-.IP "-z/--time-cond <date expression>|<file>"
+.IP "-z, --time-cond <date expression>|<file>"
 (HTTP/FTP) Request a file that has been modified later than the given time and
 date, or one that has been modified before that time. The <date expression>
 can be all sorts of date strings or if it doesn't match any internal ones, it
@@ -1959,6 +2144,8 @@ RTSP: mismatch of Session Identifiers
 unable to parse FTP file list
 .IP 88
 FTP chunk callback reported error
+.IP 89
+No connection available, the session will be queued
 .IP XX
 More error codes will appear here in future releases. The existing ones
 are meant to never change.

docs/examples/.gitignore

@@ -20,15 +20,39 @@ httpcustomheader
 httpput
 https
 imap
+imap-append
+imap-copy
+imap-create
+imap-delete
+imap-examine
+imap-fetch
+imap-list
+imap-multi
+imap-noop
+imap-search
+imap-ssl
+imap-store
+imap-tls
 multi-app
 multi-debugcallback
 multi-double
 multi-post
 multi-single
 persistant
+pop3-dele
+pop3-list
+pop3-multi
+pop3-noop
+pop3-retr
+pop3-ssl
+pop3-stat
+pop3-tls
+pop3-top
+pop3-uidl
 pop3s
 pop3slist
 post-callback
+postinmemory
 postit2
 progressfunc
 resolve
@@ -40,6 +64,12 @@ simple
 simplepost
 simplesmtp
 simplessl
+smtp-expn
+smtp-mail
 smtp-multi
+smtp-ssl
 smtp-tls
+smtp-vrfy
 url2file
+usercertinmem
+xmlstream

docs/examples/Makefile.am

@@ -43,7 +43,6 @@ LIBDIR = $(top_builddir)/lib
 # Avoid libcurl obsolete stuff
 AM_CPPFLAGS += -DCURL_NO_OLDIES
 
-# Mostly for Windows build targets, when using static libcurl
 if USE_CPPFLAG_CURL_STATICLIB
 AM_CPPFLAGS += -DCURL_STATICLIB
 endif

docs/examples/Makefile.inc

@@ -4,12 +4,17 @@ check_PROGRAMS = 10-at-a-time anyauthput cookie_interface debug fileupload \
   https multi-app multi-debugcallback multi-double multi-post multi-single \
   persistant post-callback postit2 sepheaders simple simplepost simplessl  \
   sendrecv httpcustomheader certinfo chkspeed ftpgetinfo ftp-wildcard \
-  smtp-multi simplesmtp smtp-tls rtsp externalsocket resolve \
+  smtp-mail smtp-multi smtp-ssl smtp-tls smtp-vrfy smtp-expn rtsp \
-  progressfunc pop3s pop3slist imap url2file sftpget ftpsget
+  externalsocket resolve progressfunc pop3-retr pop3-list pop3-uidl pop3-dele \
+  pop3-top pop3-stat pop3-noop pop3-ssl pop3-tls pop3-multi imap-list \
+  imap-lsub imap-fetch imap-store imap-append imap-examine imap-search \
+  imap-create imap-delete imap-copy imap-noop imap-ssl imap-tls imap-multi \
+  url2file sftpget ftpsget postinmemory
 
 # These examples require external dependencies that may not be commonly
 # available on POSIX systems, so don't bother attempting to compile them here.
 COMPLICATED_EXAMPLES = curlgtk.c curlx.c htmltitle.cpp cacertinmem.c	   \
   ftpuploadresume.c ghiper.c hiperfifo.c htmltidy.c multithread.c	   \
   opensslthreadlock.c sampleconv.c synctime.c threaded-ssl.c evhiperfifo.c \
-  smooth-gtk-thread.c version-check.pl href_extractor.c asiohiper.cpp
+  smooth-gtk-thread.c version-check.pl href_extractor.c asiohiper.cpp \
+  multi-uv.c xmlstream.c usercertinmem.c sessioninfo.c

docs/examples/Makefile.m32

@@ -27,18 +27,18 @@
 ## Example: mingw32-make -f Makefile.m32 CFG=-zlib-ssl-spi-winidn
 ##
 ## Hint: you can also set environment vars to control the build, f.e.:
-## set ZLIB_PATH=c:/zlib-1.2.7
+## set ZLIB_PATH=c:/zlib-1.2.8
 ## set ZLIB=1
 #
 ###########################################################################
 
 # Edit the path below to point to the base of your Zlib sources.
 ifndef ZLIB_PATH
-ZLIB_PATH = ../../../zlib-1.2.7
+ZLIB_PATH = ../../../zlib-1.2.8
 endif
 # Edit the path below to point to the base of your OpenSSL package.
 ifndef OPENSSL_PATH
-OPENSSL_PATH = ../../../openssl-0.9.8x
+OPENSSL_PATH = ../../../openssl-0.9.8y
 endif
 # Edit the path below to point to the base of your LibSSH2 package.
 ifndef LIBSSH2_PATH

docs/examples/Makefile.netware

@@ -14,12 +14,12 @@ endif
 
 # Edit the path below to point to the base of your Zlib sources.
 ifndef ZLIB_PATH
-ZLIB_PATH = ../../../zlib-1.2.7
+ZLIB_PATH = ../../../zlib-1.2.8
 endif
 
 # Edit the path below to point to the base of your OpenSSL package.
 ifndef OPENSSL_PATH
-OPENSSL_PATH = ../../../openssl-0.9.8x
+OPENSSL_PATH = ../../../openssl-0.9.8y
 endif
 
 # Edit the path below to point to the base of your LibSSH2 package.

docs/examples/README

@@ -61,6 +61,7 @@ multi-debugcallback.c - a multi-interface app using the debug callback
 multi-double.c - a multi-interface app doing two simultaneous transfers
 multi-post.c   - a multi-interface app doing a multipart formpost
 multi-single.c - a multi-interface app getting a single file
+multi-uv.c     - a multi-interface app using libuv
 multithread.c  - an example using multi-treading transferring multiple files
 opensslthreadlock.c - show how to do locking when using OpenSSL multi-threaded
 persistant.c   - request two URLs with a persistent connection
@@ -77,4 +78,5 @@ simplepost.c   - HTTP POST
 simplessl.c    - HTTPS example with certificates many options set
 synctime.c     - Sync local time by extracting date from remote HTTP servers
 url2file.c     - download a document and store it in a file
+xmlstream.c    - Stream-parse a document using the streaming Expat parser
 10-at-a-time.c - Download many files simultaneously, 10 at a time.

docs/examples/cacertinmem.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -103,6 +103,10 @@ static CURLcode sslctx_function(CURL * curl, void * sslctx, void * parm)
   if (X509_STORE_add_cert(store, cert)==0)
     printf("error adding certificate\n");
 
+  /* decrease reference counts */
+  X509_free(cert);
+  BIO_free(bio);
+
   /* all set to go */
   return CURLE_OK ;
 }

docs/examples/chkspeed.c

@@ -60,7 +60,7 @@ int main(int argc, char *argv[])
 {
   CURL *curl_handle;
   CURLcode res;
-  int prtsep = 0, prttime = 0;
+  int prtall = 0, prtsep = 0, prttime = 0;
   const char *url = URL_1M;
   char *appname = argv[0];
 
@@ -77,6 +77,8 @@ int main(int argc, char *argv[])
           fprintf(stderr, "\r%s %s - %s\n",
                   appname, CHKSPEED_VERSION, curl_version());
           exit(1);
+        } else if (strncasecmp(*argv, "-A", 2) == 0) {
+          prtall = 1;
         } else if (strncasecmp(*argv, "-X", 2) == 0) {
           prtsep = 1;
         } else if (strncasecmp(*argv, "-T", 2) == 0) {
@@ -161,6 +163,18 @@ int main(int argc, char *argv[])
     if((CURLE_OK == res) && (val>0))
       printf("Average download speed: %0.3f kbyte/sec.\n", val / 1024);
 
+    if (prtall) {
+      /* check for name resolution time */
+      res = curl_easy_getinfo(curl_handle, CURLINFO_NAMELOOKUP_TIME, &val);
+      if((CURLE_OK == res) && (val>0))
+        printf("Name lookup time: %0.3f sec.\n", val);
+
+      /* check for connect time */
+      res = curl_easy_getinfo(curl_handle, CURLINFO_CONNECT_TIME, &val);
+      if((CURLE_OK == res) && (val>0))
+        printf("Connect time: %0.3f sec.\n", val);
+    }
+
   } else {
     fprintf(stderr, "Error while fetching '%s' : %s\n",
             url, curl_easy_strerror(res));

docs/examples/evhiperfifo.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -133,7 +133,6 @@ static void mcode_or_die(const char *where, CURLMcode code)
     const char *s;
     switch ( code )
     {
-    case CURLM_CALL_MULTI_PERFORM: s="CURLM_CALL_MULTI_PERFORM"; break;
     case CURLM_BAD_HANDLE:         s="CURLM_BAD_HANDLE";         break;
     case CURLM_BAD_EASY_HANDLE:    s="CURLM_BAD_EASY_HANDLE";    break;
     case CURLM_OUT_OF_MEMORY:      s="CURLM_OUT_OF_MEMORY";      break;

docs/examples/getinmemory.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -42,10 +42,10 @@ WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
   struct MemoryStruct *mem = (struct MemoryStruct *)userp;
 
   mem->memory = realloc(mem->memory, mem->size + realsize + 1);
-  if (mem->memory == NULL) {
+  if(mem->memory == NULL) {
     /* out of memory! */
     printf("not enough memory (realloc returned NULL)\n");
-    exit(EXIT_FAILURE);
+    return 0;
   }
 
   memcpy(&(mem->memory[mem->size]), contents, realsize);
@@ -59,6 +59,7 @@ WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
 int main(void)
 {
   CURL *curl_handle;
+  CURLcode res;
 
   struct MemoryStruct chunk;
 
@@ -84,24 +85,27 @@ int main(void)
   curl_easy_setopt(curl_handle, CURLOPT_USERAGENT, "libcurl-agent/1.0");
 
   /* get it! */
-  curl_easy_perform(curl_handle);
+  res = curl_easy_perform(curl_handle);
+
+  /* check for errors */
+  if(res != CURLE_OK) {
+    fprintf(stderr, "curl_easy_perform() failed: %s\n",
+            curl_easy_strerror(res));
+  }
+  else {
+    /*
+     * Now, our chunk.memory points to a memory block that is chunk.size
+     * bytes big and contains the remote file.
+     *
+     * Do something nice with it!
+     */
+
+    printf("%lu bytes retrieved\n", (long)chunk.size);
+  }
 
   /* cleanup curl stuff */
   curl_easy_cleanup(curl_handle);
 
-  /*
-   * Now, our chunk.memory points to a memory block that is chunk.size
-   * bytes big and contains the remote file.
-   *
-   * Do something nice with it!
-   *
-   * You should be aware of the fact that at this point we might have an
-   * allocated data block, and nothing has yet deallocated that data. So when
-   * you're done with it, you should free() it as a nice application.
-   */
-
-  printf("%lu bytes retrieved\n", (long)chunk.size);
-
   if(chunk.memory)
     free(chunk.memory);
 

docs/examples/ghiper.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -104,7 +104,6 @@ static void mcode_or_die(const char *where, CURLMcode code) {
   if ( CURLM_OK != code ) {
     const char *s;
     switch (code) {
-      case     CURLM_CALL_MULTI_PERFORM: s="CURLM_CALL_MULTI_PERFORM"; break;
       case     CURLM_BAD_HANDLE:         s="CURLM_BAD_HANDLE";         break;
       case     CURLM_BAD_EASY_HANDLE:    s="CURLM_BAD_EASY_HANDLE";    break;
       case     CURLM_OUT_OF_MEMORY:      s="CURLM_OUT_OF_MEMORY";      break;

docs/examples/hiperfifo.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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,7 +24,7 @@
 
 Written by Jeff Pohlmeyer
 
-Requires libevent and a (POSIX?) system that has mkfifo().
+Requires libevent version 2 and a (POSIX?) system that has mkfifo().
 
 This is an adaptation of libcurl's "hipev.c" and libevent's "event-test.c"
 sample programs.
@@ -61,7 +61,7 @@ callback.
 #include <unistd.h>
 #include <sys/poll.h>
 #include <curl/curl.h>
-#include <event.h>
+#include <event2/event.h>
 #include <fcntl.h>
 #include <sys/stat.h>
 #include <errno.h>
@@ -71,9 +71,11 @@ callback.
 
 
 /* Global information, common to all connections */
-typedef struct _GlobalInfo {
+typedef struct _GlobalInfo
-  struct event fifo_event;
+{
-  struct event timer_event;
+  struct event_base *evbase;
+  struct event *fifo_event;
+  struct event *timer_event;
   CURLM *multi;
   int still_running;
   FILE* input;
@@ -81,7 +83,8 @@ typedef struct _GlobalInfo {
 
 
 /* Information associated with a specific easy handle */
-typedef struct _ConnInfo {
+typedef struct _ConnInfo
+{
   CURL *easy;
   char *url;
   GlobalInfo *global;
@@ -90,12 +93,13 @@ typedef struct _ConnInfo {
 
 
 /* Information associated with a specific socket */
-typedef struct _SockInfo {
+typedef struct _SockInfo
+{
   curl_socket_t sockfd;
   CURL *easy;
   int action;
   long timeout;
-  struct event ev;
+  struct event *ev;
   int evset;
   GlobalInfo *global;
 } SockInfo;
@@ -111,7 +115,7 @@ static int multi_timer_cb(CURLM *multi, long timeout_ms, GlobalInfo *g)
   timeout.tv_sec = timeout_ms/1000;
   timeout.tv_usec = (timeout_ms%1000)*1000;
   fprintf(MSG_OUT, "multi_timer_cb: Setting timeout to %ld ms\n", timeout_ms);
-  evtimer_add(&g->timer_event, &timeout);
+  evtimer_add(g->timer_event, &timeout);
   return 0;
 }
 
@@ -121,7 +125,6 @@ static void mcode_or_die(const char *where, CURLMcode code)
   if ( CURLM_OK != code ) {
     const char *s;
     switch (code) {
-      case     CURLM_CALL_MULTI_PERFORM: s="CURLM_CALL_MULTI_PERFORM"; break;
       case     CURLM_BAD_HANDLE:         s="CURLM_BAD_HANDLE";         break;
       case     CURLM_BAD_EASY_HANDLE:    s="CURLM_BAD_EASY_HANDLE";    break;
       case     CURLM_OUT_OF_MEMORY:      s="CURLM_OUT_OF_MEMORY";      break;
@@ -186,8 +189,8 @@ static void event_cb(int fd, short kind, void *userp)
   check_multi_info(g);
   if ( g->still_running <= 0 ) {
     fprintf(MSG_OUT, "last transfer done, kill timeout\n");
-    if (evtimer_pending(&g->timer_event, NULL)) {
+    if (evtimer_pending(g->timer_event, NULL)) {
-      evtimer_del(&g->timer_event);
+      evtimer_del(g->timer_event);
     }
   }
 }
@@ -215,7 +218,7 @@ static void remsock(SockInfo *f)
 {
   if (f) {
     if (f->evset)
-      event_del(&f->ev);
+      event_free(f->ev);
     free(f);
   }
 }
@@ -232,16 +235,17 @@ static void setsock(SockInfo*f, curl_socket_t s, CURL*e, int act, GlobalInfo*g)
   f->action = act;
   f->easy = e;
   if (f->evset)
-    event_del(&f->ev);
+    event_free(f->ev);
-  event_set(&f->ev, f->sockfd, kind, event_cb, g);
+  f->ev = event_new(g->evbase, f->sockfd, kind, event_cb, g);
-  f->evset=1;
+  f->evset = 1;
-  event_add(&f->ev, NULL);
+  event_add(f->ev, NULL);
 }
 
 
 
 /* Initialize a new SockInfo structure */
-static void addsock(curl_socket_t s, CURL *easy, int action, GlobalInfo *g) {
+static void addsock(curl_socket_t s, CURL *easy, int action, GlobalInfo *g)
+{
   SockInfo *fdp = calloc(sizeof(SockInfo), 1);
 
   fdp->global = g;
@@ -359,10 +363,10 @@ static void fifo_cb(int fd, short event, void *arg)
 }
 
 /* Create a named pipe and tell libevent to monitor it */
+static const char *fifo = "hiper.fifo";
 static int init_fifo (GlobalInfo *g)
 {
   struct stat st;
-  static const char *fifo = "hiper.fifo";
   curl_socket_t sockfd;
 
   fprintf(MSG_OUT, "Creating named pipe \"%s\"\n", fifo);
@@ -386,11 +390,18 @@ static int init_fifo (GlobalInfo *g)
   g->input = fdopen(sockfd, "r");
 
   fprintf(MSG_OUT, "Now, pipe some URL's into > %s\n", fifo);
-  event_set(&g->fifo_event, sockfd, EV_READ | EV_PERSIST, fifo_cb, g);
+  g->fifo_event = event_new(g->evbase, sockfd, EV_READ|EV_PERSIST, fifo_cb, g);
-  event_add(&g->fifo_event, NULL);
+  event_add(g->fifo_event, NULL);
   return (0);
 }
 
+static void clean_fifo(GlobalInfo *g)
+{
+    event_free(g->fifo_event);
+    fclose(g->input);
+    unlink(fifo);
+}
+
 int main(int argc, char **argv)
 {
   GlobalInfo g;
@@ -398,10 +409,10 @@ int main(int argc, char **argv)
   (void)argv;
 
   memset(&g, 0, sizeof(GlobalInfo));
-  event_init();
+  g.evbase = event_base_new();
   init_fifo(&g);
   g.multi = curl_multi_init();
-  evtimer_set(&g.timer_event, timer_cb, &g);
+  g.timer_event = evtimer_new(g.evbase, timer_cb, &g);
 
   /* setup the generic multi interface options we want */
   curl_multi_setopt(g.multi, CURLMOPT_SOCKETFUNCTION, sock_cb);
@@ -412,7 +423,13 @@ int main(int argc, char **argv)
   /* we don't call any curl_multi_socket*() function yet as we have no handles
      added! */
 
-  event_dispatch();
+  event_base_dispatch(g.evbase);
+
+  /* this, of course, won't get called since only way to stop this program is
+     via ctrl-C, but it is here to show how cleanup /would/ be done. */
+  clean_fifo(&g);
+  event_free(g.timer_event);
+  event_base_free(g.evbase);
   curl_multi_cleanup(g.multi);
   return 0;
 }

docs/examples/htmltitle.cpp

@@ -25,7 +25,7 @@
 //
 // GNU C++ compile command line suggestion (edit paths accordingly):
 //
-// g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cc \
+// g++ -Wall -I/opt/curl/include -I/opt/libxml/include/libxml2 htmltitle.cpp \
 // -o htmltitle -L/opt/curl/lib -L/opt/libxml/lib -lcurl -lxml2
 
 #include <stdio.h>

docs/examples/httpput.c

@@ -22,8 +22,6 @@
 #include <stdio.h>
 #include <fcntl.h>
 #include <sys/stat.h>
-#include <unistd.h>
-
 #include <curl/curl.h>
 
 /*
@@ -59,7 +57,6 @@ int main(int argc, char **argv)
   CURL *curl;
   CURLcode res;
   FILE * hd_src ;
-  int hd ;
   struct stat file_info;
 
   char *file;
@@ -72,9 +69,7 @@ int main(int argc, char **argv)
   url = argv[2];
 
   /* get the file size of the local file */
-  hd = open(file, O_RDONLY) ;
+  stat(file, &file_info);
-  fstat(hd, &file_info);
-  close(hd) ;
 
   /* get a FILE * of the same file, could also be made with
      fdopen() from the previous descriptor, but hey this is just

docs/examples/imap-append.c

@@ -0,0 +1,116 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <string.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to send mail using libcurl's IMAP
+ * capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+#define FROM    "<sender@example.org>"
+#define TO      "<addressee@example.net>"
+#define CC      "<info@example.org>"
+
+static const char *payload_text[] = {
+  "Date: Mon, 29 Nov 2010 21:54:29 +1100\r\n",
+  "To: " TO "\r\n",
+  "From: " FROM "(Example User)\r\n",
+  "Cc: " CC "(Another example User)\r\n",
+  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
+  "Subject: IMAP example message\r\n",
+  "\r\n", /* empty line to divide headers from body, see RFC5322 */
+  "The body of the message starts here.\r\n",
+  "\r\n",
+  "It could be a lot of lines, could be MIME encoded, whatever.\r\n",
+  "Check RFC5322.\r\n",
+  NULL
+};
+
+struct upload_status {
+  int lines_read;
+};
+
+static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp)
+{
+  struct upload_status *upload_ctx = (struct upload_status *)userp;
+  const char *data;
+
+  if((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
+    return 0;
+  }
+
+  data = payload_text[upload_ctx->lines_read];
+
+  if(data) {
+    size_t len = strlen(data);
+    memcpy(ptr, data, len);
+    upload_ctx->lines_read++;
+
+    return len;
+  }
+
+  return 0;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+  struct upload_status upload_ctx;
+
+  upload_ctx.lines_read = 0;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will create a new message 100. Note that you should perform an
+     * EXAMINE command to obtain the UID of the next message to create and a
+     * SELECT to ensure you are creating the message in the OUTBOX. */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/100");
+
+    /* In this case, we're using a callback function to specify the data. You
+     * could just use the CURLOPT_READDATA option to specify a FILE pointer to
+     * read from. */
+    curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
+    curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
+
+    /* Perform the append */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-copy.c

@@ -0,0 +1,65 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to copy a mail from one mailbox folder
+ * to another using libcurl's IMAP capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is source mailbox folder to select */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX");
+
+    /* Set the COPY command specifing the message ID and destination folder */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "COPY 1 FOLDER");
+
+    /* Note that to perform a move operation you will need to perform the copy,
+     * then mark the original mail as Deleted and EXPUNGE or CLOSE. Please see
+     * imap-store.c for more information on deleting messages. */
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-create.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to create a new mailbox folder using
+ * libcurl's IMAP capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Set the CREATE command specifing the new folder name */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "CREATE FOLDER");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-delete.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to delete an existing mailbox folder
+ * using libcurl's IMAP capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Set the DELETE command specifing the existing folder */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELETE FOLDER");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-examine.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to obtain information about a mailbox
+ * folder using libcurl's IMAP capabilities via the EXAMINE command.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Set the EXAMINE command specifing the mailbox folder */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "EXAMINE OUTBOX");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-fetch.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -22,6 +22,12 @@
 #include <stdio.h>
 #include <curl/curl.h>
 
+/* This is a simple example showing how to fetch mail using libcurl's IMAP
+ * capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
 int main(void)
 {
   CURL *curl;
@@ -30,15 +36,23 @@ int main(void)
   curl = curl_easy_init();
   if(curl) {
     /* Set username and password */
-    curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password");
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
 
-    /* This will fetch the mailbox named "foobar" */
+    /* This will fetch message 1 from the user's inbox */
-    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/foobar");
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1");
 
+    /* Perform the fetch */
     res = curl_easy_perform(curl);
 
-    /* always cleanup */
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
     curl_easy_cleanup(curl);
   }
+
   return (int)res;
 }

docs/examples/imap-list.c

@@ -0,0 +1,60 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to list the folders within an IMAP
+ * mailbox.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will list the folders within the user's mailbox. If you want to
+     * list the folders within a specific folder, for example the inbox, then
+     * specify the folder as a path in the URL such as /INBOX */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Perform the list */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-lsub.c

@@ -0,0 +1,62 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to list the subscribed folders within
+ * an IMAP mailbox.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Set the LSUB command. Note the syntax is very similar to that of a LIST
+       command. */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "LSUB \"\" *");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-multi.c

@@ -0,0 +1,145 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to fetch mail using libcurl's IMAP
+ * capabilities. It builds on the imap-fetch.c example to demonstrate how to
+ * use libcurl's multi interface.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+#define MULTI_PERFORM_HANG_TIMEOUT 60 * 1000
+
+static struct timeval tvnow(void)
+{
+  struct timeval now;
+
+  /* time() returns the value of time in seconds since the epoch */
+  now.tv_sec = (long)time(NULL);
+  now.tv_usec = 0;
+
+  return now;
+}
+
+static long tvdiff(struct timeval newer, struct timeval older)
+{
+  return (newer.tv_sec - older.tv_sec) * 1000 +
+    (newer.tv_usec - older.tv_usec) / 1000;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLM *mcurl;
+  int still_running = 1;
+  struct timeval mp_start;
+
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
+  curl = curl_easy_init();
+  if(!curl)
+    return 1;
+
+  mcurl = curl_multi_init();
+  if(!mcurl)
+    return 2;
+
+  /* Set username and password */
+  curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+  curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+  /* This will fetch message 1 from the user's inbox */
+  curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1");
+
+  /* Tell the multi stack about our easy handle */
+  curl_multi_add_handle(mcurl, curl);
+
+  /* Record the start time which we can use later */
+  mp_start = tvnow();
+
+  /* We start some action by calling perform right away */
+  curl_multi_perform(mcurl, &still_running);
+
+  while(still_running) {
+    struct timeval timeout;
+    fd_set fdread;
+    fd_set fdwrite;
+    fd_set fdexcep;
+    int maxfd = -1;
+    int rc;
+
+    long curl_timeo = -1;
+
+    /* Initialise the file descriptors */
+    FD_ZERO(&fdread);
+    FD_ZERO(&fdwrite);
+    FD_ZERO(&fdexcep);
+
+    /* Set a suitable timeout to play around with */
+    timeout.tv_sec = 1;
+    timeout.tv_usec = 0;
+
+    curl_multi_timeout(mcurl, &curl_timeo);
+    if(curl_timeo >= 0) {
+      timeout.tv_sec = curl_timeo / 1000;
+      if(timeout.tv_sec > 1)
+        timeout.tv_sec = 1;
+      else
+        timeout.tv_usec = (curl_timeo % 1000) * 1000;
+    }
+
+    /* Get file descriptors from the transfers */
+    curl_multi_fdset(mcurl, &fdread, &fdwrite, &fdexcep, &maxfd);
+
+    /* In a real-world program you OF COURSE check the return code of the
+       function calls.  On success, the value of maxfd is guaranteed to be
+       greater or equal than -1.  We call select(maxfd + 1, ...), specially in
+       case of (maxfd == -1), we call select(0, ...), which is basically equal
+       to sleep. */
+    rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
+
+    if(tvdiff(tvnow(), mp_start) > MULTI_PERFORM_HANG_TIMEOUT) {
+      fprintf(stderr,
+              "ABORTING: Since it seems that we would have run forever.\n");
+      break;
+    }
+
+    switch(rc) {
+    case -1:  /* select error */
+      break;
+    case 0:   /* timeout */
+    default:  /* action */
+      curl_multi_perform(mcurl, &still_running);
+      break;
+    }
+  }
+
+  /* Always cleanup */
+  curl_multi_remove_handle(mcurl, curl);
+  curl_multi_cleanup(mcurl);
+  curl_easy_cleanup(curl);
+  curl_global_cleanup();
+
+  return 0;
+}

docs/examples/imap-noop.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to perform a noop using libcurl's IMAP
+ * capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com");
+
+    /* Set the NOOP command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "NOOP");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-search.c

@@ -0,0 +1,65 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to search for new messages using
+ * libcurl's IMAP capabilities.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is mailbox folder to select */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX");
+
+    /* Set the SEARCH command specifing what we want to search for. Note that
+     * this can contain a message sequence set and a number of search criteria
+     * keywords including flags such as ANSWERED, DELETED, DRAFT, FLAGGED, NEW,
+     * RECENT and SEEN. For more information about the search criteria please
+     * see RFC-3501 section 6.4.4.   */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "SEARCH NEW");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-ssl.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -22,52 +22,64 @@
 #include <stdio.h>
 #include <curl/curl.h>
 
+/* This is a simple example showing how to fetch mail using libcurl's IMAP
+ * capabilities. It builds on the imap-fetch.c example adding transport
+ * security to protect the authentication details from being snooped.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
 int main(void)
 {
   CURL *curl;
-  CURLcode res;
+  CURLcode res = CURLE_OK;
 
   curl = curl_easy_init();
   if(curl) {
     /* Set username and password */
-    curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password");
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
 
-    /* This will list every message of the given mailbox */
+    /* This will fetch message 1 from the user's inbox. Note the use of
-    curl_easy_setopt(curl, CURLOPT_URL, "pop3s://user@pop.example.com/");
+    * imaps:// rather than imap:// to request a SSL based connection. */
+    curl_easy_setopt(curl, CURLOPT_URL, "imaps://imap.example.com/INBOX/;UID=1");
 
-#ifdef SKIP_PEER_VERIFICATION
+    /* If you want to connect to a site who isn't using a certificate that is
-    /*
-     * If you want to connect to a site who isn't using a certificate that is
      * signed by one of the certs in the CA bundle you have, you can skip the
      * verification of the server's certificate. This makes the connection
      * A LOT LESS SECURE.
      *
      * If you have a CA cert for the server stored someplace else than in the
      * default bundle, then the CURLOPT_CAPATH option might come handy for
-     * you.
+     * you. */
-     */
+#ifdef SKIP_PEER_VERIFICATION
     curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
 #endif
 
-#ifdef SKIP_HOSTNAME_VERFICATION
+    /* If the site you're connecting to uses a different host name that what
-    /*
-     * If the site you're connecting to uses a different host name that what
      * they have mentioned in their server certificate's commonName (or
      * subjectAltName) fields, libcurl will refuse to connect. You can skip
-     * this check, but this will make the connection less secure.
+     * this check, but this will make the connection less secure. */
-     */
+#ifdef SKIP_HOSTNAME_VERFICATION
     curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
 #endif
 
-    /* Perform the request, res will get the return code */
+    /* Since the traffic will be encrypted, it is very useful to turn on debug
+     * information within libcurl to see what is happening during the
+     * transfer */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    /* Perform the fetch */
     res = curl_easy_perform(curl);
+
     /* Check for errors */
     if(res != CURLE_OK)
       fprintf(stderr, "curl_easy_perform() failed: %s\n",
               curl_easy_strerror(res));
 
-    /* always cleanup */
+    /* Always cleanup */
     curl_easy_cleanup(curl);
   }
-  return 0;
+
+  return (int)res;
 }

docs/examples/imap-store.c

@@ -0,0 +1,76 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to modify an existing mail using
+ * libcurl's IMAP capabilities with the STORE command.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is the mailbox folder to select */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX");
+
+    /* Set the STORE command with the Deleted flag for message 1. Note that
+     * you can use the STORE command to set other flags such as Seen, Answered,
+     * Flagged, Draft and Recent. */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "STORE 1 +Flags \\Deleted");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+    else {
+      /* Set the EXPUNGE command, although you can use the CLOSE command if you
+       * don't want to know the result of the STORE */
+      curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "EXPUNGE");
+
+      /* Perform the second custom request */
+      res = curl_easy_perform(curl);
+
+      /* Check for errors */
+      if(res != CURLE_OK)
+        fprintf(stderr, "curl_easy_perform() failed: %s\n",
+                curl_easy_strerror(res));
+    }
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/imap-tls.c

@@ -0,0 +1,84 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to fetch mail using libcurl's IMAP
+ * capabilities. It builds on the imap-fetch.c example adding transport
+ * security to protect the authentication details from being snooped.
+ *
+ * Note that this example requires libcurl 7.30.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will fetch message 1 from the user's inbox */
+    curl_easy_setopt(curl, CURLOPT_URL, "imap://imap.example.com/INBOX/;UID=1");
+
+    /* In this example, we'll start with a plain text connection, and upgrade
+     * to Transport Layer Security (TLS) using the STARTTLS command. Be careful
+     * of using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer
+     * will continue anyway - see the security discussion in the libcurl
+     * tutorial for more details. */
+    curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
+
+    /* If your server doesn't have a valid certificate, then you can disable
+     * part of the Transport Layer Security protection by setting the
+     * CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false).
+     *   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+     *   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+     * That is, in general, a bad idea. It is still better than sending your
+     * authentication details in plain text though.
+     * Instead, you should get the issuer certificate (or the host certificate
+     * if the certificate is self-signed) and add it to the set of certificates
+     * that are known to libcurl using CURLOPT_CAINFO and/or CURLOPT_CAPATH. See
+     * docs/SSLCERTS for more information. */
+    curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem");
+
+    /* Since the traffic will be encrypted, it is very useful to turn on debug
+     * information within libcurl to see what is happening during the
+     * transfer */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    /* Perform the fetch */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/multi-single.c

@@ -41,6 +41,8 @@ int main(void)
 
   int still_running; /* keep number of running handles */
 
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
   http_handle = curl_easy_init();
 
   /* set the options (I left out a few, you'll get the point anyway) */
@@ -108,9 +110,13 @@ int main(void)
     }
   } while(still_running);
 
-  curl_multi_cleanup(multi_handle);
+  curl_multi_remove_handle(multi_handle, http_handle);
 
   curl_easy_cleanup(http_handle);
 
+  curl_multi_cleanup(multi_handle);
+
+  curl_global_cleanup();
+
   return 0;
 }

docs/examples/multi-uv.c

@@ -0,0 +1,212 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2013, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+
+/* Example application code using the multi socket interface to download
+   multiple files at once, but instead of using curl_multi_perform and
+   curl_multi_wait, which uses select(), we use libuv.
+   It supports epoll, kqueue, etc. on unixes and fast IO completion ports on
+   Windows, which means, it should be very fast on all platforms..
+
+   Written by Clemens Gruber, based on an outdated example from uvbook and
+   some tests from libuv.
+
+   Requires libuv and (of course) libcurl.
+
+   See http://nikhilm.github.com/uvbook/ for more information on libuv.
+*/
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <uv.h>
+#include <curl/curl.h>
+
+uv_loop_t *loop;
+CURLM *curl_handle;
+uv_timer_t timeout;
+
+typedef struct curl_context_s {
+  uv_poll_t poll_handle;
+  curl_socket_t sockfd;
+} curl_context_t;
+
+curl_context_t* create_curl_context(curl_socket_t sockfd)
+{
+  curl_context_t *context;
+
+  context = (curl_context_t *) malloc(sizeof *context);
+
+  context->sockfd = sockfd;
+
+  uv_poll_init_socket(loop, &context->poll_handle, sockfd);
+  context->poll_handle.data = context;
+
+  return context;
+}
+
+void curl_close_cb(uv_handle_t *handle)
+{
+  curl_context_t* context = (curl_context_t*) handle->data;
+  free(context);
+}
+
+void destroy_curl_context(curl_context_t *context)
+{
+  uv_close((uv_handle_t*) &context->poll_handle, curl_close_cb);
+}
+
+
+void add_download(const char *url, int num)
+{
+  char filename[50];
+  FILE *file;
+  CURL *handle;
+
+  sprintf(filename, "%d.download", num);
+
+  file = fopen(filename, "w");
+  if (file == NULL) {
+    fprintf(stderr, "Error opening %s\n", filename);
+    return;
+  }
+
+  handle = curl_easy_init();
+  curl_easy_setopt(handle, CURLOPT_WRITEDATA, file);
+  curl_easy_setopt(handle, CURLOPT_URL, url);
+  curl_multi_add_handle(curl_handle, handle);
+  fprintf(stderr, "Added download %s -> %s\n", url, filename);
+}
+
+void curl_perform(uv_poll_t *req, int status, int events)
+{
+  int running_handles;
+  int flags = 0;
+  curl_context_t *context;
+  char *done_url;
+  CURLMsg *message;
+  int pending;
+
+  uv_timer_stop(&timeout);
+
+  if (events & UV_READABLE)
+    flags |= CURL_CSELECT_IN;
+  if (events & UV_WRITABLE)
+    flags |= CURL_CSELECT_OUT;
+
+  context = (curl_context_t*)req;
+
+  curl_multi_socket_action(curl_handle, context->sockfd, flags,
+                           &running_handles);
+
+  while ((message = curl_multi_info_read(curl_handle, &pending))) {
+    switch (message->msg) {
+    case CURLMSG_DONE:
+      curl_easy_getinfo(message->easy_handle, CURLINFO_EFFECTIVE_URL,
+                        &done_url);
+      printf("%s DONE\n", done_url);
+
+      curl_multi_remove_handle(curl_handle, message->easy_handle);
+      curl_easy_cleanup(message->easy_handle);
+
+      break;
+    default:
+      fprintf(stderr, "CURLMSG default\n");
+      abort();
+    }
+  }
+}
+
+void on_timeout(uv_timer_t *req, int status)
+{
+  int running_handles;
+  curl_multi_socket_action(curl_handle, CURL_SOCKET_TIMEOUT, 0,
+                           &running_handles);
+}
+
+void start_timeout(CURLM *multi, long timeout_ms, void *userp)
+{
+  if (timeout_ms <= 0)
+    timeout_ms = 1; /* 0 means directly call socket_action, but we'll do it in
+                       a bit */
+  uv_timer_start(&timeout, on_timeout, timeout_ms, 0);
+}
+
+int handle_socket(CURL *easy, curl_socket_t s, int action, void *userp,
+                  void *socketp)
+{
+  curl_context_t *curl_context;
+  if (action == CURL_POLL_IN || action == CURL_POLL_OUT) {
+    if (socketp) {
+      curl_context = (curl_context_t*) socketp;
+    }
+    else {
+      curl_context = create_curl_context(s);
+    }
+    curl_multi_assign(curl_handle, s, (void *) curl_context);
+  }
+
+  switch (action) {
+  case CURL_POLL_IN:
+    uv_poll_start(&curl_context->poll_handle, UV_READABLE, curl_perform);
+    break;
+  case CURL_POLL_OUT:
+    uv_poll_start(&curl_context->poll_handle, UV_WRITABLE, curl_perform);
+    break;
+  case CURL_POLL_REMOVE:
+    if (socketp) {
+      uv_poll_stop(&((curl_context_t*)socketp)->poll_handle);
+      destroy_curl_context((curl_context_t*) socketp);
+      curl_multi_assign(curl_handle, s, NULL);
+    }
+    break;
+  default:
+    abort();
+  }
+
+  return 0;
+}
+
+int main(int argc, char **argv)
+{
+  loop = uv_default_loop();
+
+  if (argc <= 1)
+    return 0;
+
+  if (curl_global_init(CURL_GLOBAL_ALL)) {
+    fprintf(stderr, "Could not init cURL\n");
+    return 1;
+  }
+
+  uv_timer_init(loop, &timeout);
+
+  curl_handle = curl_multi_init();
+  curl_multi_setopt(curl_handle, CURLMOPT_SOCKETFUNCTION, handle_socket);
+  curl_multi_setopt(curl_handle, CURLMOPT_TIMERFUNCTION, start_timeout);
+
+  while (argc-- > 1) {
+    add_download(argv[argc], argc);
+  }
+
+  uv_run(loop, UV_RUN_DEFAULT);
+  curl_multi_cleanup(curl_handle);
+  return 0;
+}

docs/examples/pop3-dele.c

@@ -0,0 +1,64 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to delete an existing mail using
+ * libcurl's POP3 capabilities.
+ *
+ * Note that this example requires libcurl 7.26.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* You can specify the message either in the URL or DELE command */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
+
+    /* Set the DELE command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "DELE");
+
+    /* Do not perform a transfer as DELE returns no data */
+    curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-list.c

@@ -0,0 +1,58 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example using libcurl's POP3 capabilities to list the
+ * contents of a mailbox.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will list every message of the given mailbox */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com");
+
+    /* Perform the list */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-multi.c

@@ -0,0 +1,145 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to retrieve mail using libcurl's POP3
+ * capabilities. It builds on the pop3-retr.c example to demonstrate how to use
+ * libcurl's multi interface.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+#define MULTI_PERFORM_HANG_TIMEOUT 60 * 1000
+
+static struct timeval tvnow(void)
+{
+  struct timeval now;
+
+  /* time() returns the value of time in seconds since the epoch */
+  now.tv_sec = (long)time(NULL);
+  now.tv_usec = 0;
+
+  return now;
+}
+
+static long tvdiff(struct timeval newer, struct timeval older)
+{
+  return (newer.tv_sec - older.tv_sec) * 1000 +
+    (newer.tv_usec - older.tv_usec) / 1000;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLM *mcurl;
+  int still_running = 1;
+  struct timeval mp_start;
+
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
+  curl = curl_easy_init();
+  if(!curl)
+    return 1;
+
+  mcurl = curl_multi_init();
+  if(!mcurl)
+    return 2;
+
+  /* Set username and password */
+  curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+  curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+  /* This will retreive message 1 from the user's mailbox */
+  curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
+
+  /* Tell the multi stack about our easy handle */
+  curl_multi_add_handle(mcurl, curl);
+
+  /* Record the start time which we can use later */
+  mp_start = tvnow();
+
+  /* We start some action by calling perform right away */
+  curl_multi_perform(mcurl, &still_running);
+
+  while(still_running) {
+    struct timeval timeout;
+    fd_set fdread;
+    fd_set fdwrite;
+    fd_set fdexcep;
+    int maxfd = -1;
+    int rc;
+
+    long curl_timeo = -1;
+
+    /* Initialise the file descriptors */
+    FD_ZERO(&fdread);
+    FD_ZERO(&fdwrite);
+    FD_ZERO(&fdexcep);
+
+    /* Set a suitable timeout to play around with */
+    timeout.tv_sec = 1;
+    timeout.tv_usec = 0;
+
+    curl_multi_timeout(mcurl, &curl_timeo);
+    if(curl_timeo >= 0) {
+      timeout.tv_sec = curl_timeo / 1000;
+      if(timeout.tv_sec > 1)
+        timeout.tv_sec = 1;
+      else
+        timeout.tv_usec = (curl_timeo % 1000) * 1000;
+    }
+
+    /* Get file descriptors from the transfers */
+    curl_multi_fdset(mcurl, &fdread, &fdwrite, &fdexcep, &maxfd);
+
+    /* In a real-world program you OF COURSE check the return code of the
+       function calls. On success, the value of maxfd is guaranteed to be
+       greater or equal than -1. We call select(maxfd + 1, ...), specially in
+       case of (maxfd == -1), we call select(0, ...), which is basically equal
+       to sleep. */
+    rc = select(maxfd + 1, &fdread, &fdwrite, &fdexcep, &timeout);
+
+    if(tvdiff(tvnow(), mp_start) > MULTI_PERFORM_HANG_TIMEOUT) {
+      fprintf(stderr,
+              "ABORTING: Since it seems that we would have run forever.\n");
+      break;
+    }
+
+    switch(rc) {
+    case -1:  /* select error */
+      break;
+    case 0:   /* timeout */
+    default:  /* action */
+      curl_multi_perform(mcurl, &still_running);
+      break;
+    }
+  }
+
+  /* Always cleanup */
+  curl_multi_remove_handle(mcurl, curl);
+  curl_multi_cleanup(mcurl);
+  curl_easy_cleanup(curl);
+  curl_global_cleanup();
+
+  return 0;
+}

docs/examples/pop3-noop.c

@@ -0,0 +1,64 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to perform a noop using libcurl's POP3
+ * capabilities.
+ *
+ * Note that this example requires libcurl 7.26.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com");
+
+    /* Set the NOOP command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "NOOP");
+
+    /* Do not perform a transfer as NOOP returns no data */
+    curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-retr.c

@@ -0,0 +1,58 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to retrieve mail using libcurl's POP3
+ * capabilities.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will retreive message 1 from the user's mailbox */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
+
+    /* Perform the retr */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-ssl.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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
@@ -22,52 +22,64 @@
 #include <stdio.h>
 #include <curl/curl.h>
 
+/* This is a simple example showing how to retrieve mail using libcurl's POP3
+ * capabilities. It builds on the pop3-retr.c example adding transport
+ * security to protect the authentication details from being snooped.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
 int main(void)
 {
   CURL *curl;
-  CURLcode res;
+  CURLcode res = CURLE_OK;
 
   curl = curl_easy_init();
   if(curl) {
     /* Set username and password */
-    curl_easy_setopt(curl, CURLOPT_USERPWD, "user:password");
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
 
-    /* This will only fetch the message with ID "1" of the given mailbox */
+    /* This will retreive message 1 from the user's mailbox. Note the use of
-    curl_easy_setopt(curl, CURLOPT_URL, "pop3s://user@pop.example.com/1");
+     * pop3s:// rather than pop3:// to request a SSL based connection. */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3s://pop.example.com/1");
 
-#ifdef SKIP_PEER_VERIFICATION
+    /* If you want to connect to a site who isn't using a certificate that is
-    /*
-     * If you want to connect to a site who isn't using a certificate that is
      * signed by one of the certs in the CA bundle you have, you can skip the
      * verification of the server's certificate. This makes the connection
      * A LOT LESS SECURE.
      *
      * If you have a CA cert for the server stored someplace else than in the
      * default bundle, then the CURLOPT_CAPATH option might come handy for
-     * you.
+     * you. */
-     */
+#ifdef SKIP_PEER_VERIFICATION
     curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
 #endif
 
-#ifdef SKIP_HOSTNAME_VERFICATION
+    /* If the site you're connecting to uses a different host name that what
-    /*
-     * If the site you're connecting to uses a different host name that what
      * they have mentioned in their server certificate's commonName (or
      * subjectAltName) fields, libcurl will refuse to connect. You can skip
-     * this check, but this will make the connection less secure.
+     * this check, but this will make the connection less secure. */
-     */
+#ifdef SKIP_HOSTNAME_VERFICATION
     curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
 #endif
 
-    /* Perform the request, res will get the return code */
+    /* Since the traffic will be encrypted, it is very useful to turn on debug
+     * information within libcurl to see what is happening during the
+     * transfer */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    /* Perform the retr */
     res = curl_easy_perform(curl);
+
     /* Check for errors */
     if(res != CURLE_OK)
       fprintf(stderr, "curl_easy_perform() failed: %s\n",
               curl_easy_strerror(res));
 
-    /* always cleanup */
+    /* Always cleanup */
     curl_easy_cleanup(curl);
   }
-  return 0;
+
+  return (int)res;
 }

docs/examples/pop3-stat.c

@@ -0,0 +1,64 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to obtain message statistics using
+ * libcurl's POP3 capabilities.
+ *
+ * Note that this example requires libcurl 7.26.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com");
+
+    /* Set the STAT command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "STAT");
+
+    /* Do not perform a transfer as the data is in the response */
+    curl_easy_setopt(curl, CURLOPT_NOBODY, 1L);
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-tls.c

@@ -0,0 +1,84 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to retrieve mail using libcurl's POP3
+ * capabilities. It builds on the pop3-retr.c example adding transport
+ * security to protect the authentication details from being snooped.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This will retreive message 1 from the user's mailbox */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com/1");
+
+    /* In this example, we'll start with a plain text connection, and upgrade
+     * to Transport Layer Security (TLS) using the STLS command. Be careful of
+     * using CURLUSESSL_TRY here, because if TLS upgrade fails, the transfer
+     * will continue anyway - see the security discussion in the libcurl
+     * tutorial for more details. */
+    curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
+
+    /* If your server doesn't have a valid certificate, then you can disable
+     * part of the Transport Layer Security protection by setting the
+     * CURLOPT_SSL_VERIFYPEER and CURLOPT_SSL_VERIFYHOST options to 0 (false).
+     *   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+     *   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+     * That is, in general, a bad idea. It is still better than sending your
+     * authentication details in plain text though.
+     * Instead, you should get the issuer certificate (or the host certificate
+     * if the certificate is self-signed) and add it to the set of certificates
+     * that are known to libcurl using CURLOPT_CAINFO and/or CURLOPT_CAPATH. See
+     * docs/SSLCERTS for more information. */
+    curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem");
+
+    /* Since the traffic will be encrypted, it is very useful to turn on debug
+     * information within libcurl to see what is happening during the
+     * transfer */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    /* Perform the retr */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-top.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to retrieve only the headers of a mail
+ * using libcurl's POP3 capabilities.
+ *
+ * Note that this example requires libcurl 7.26.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com");
+
+    /* Set the TOP command for message 1 to only include the headers */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "TOP 1 0");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/pop3-uidl.c

@@ -0,0 +1,61 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <curl/curl.h>
+
+/* This is a simple example using libcurl's POP3 capabilities to list the
+ * contents of a mailbox by unique ID.
+ *
+ * Note that this example requires libcurl 7.26.0 or above.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is just the server URL */
+    curl_easy_setopt(curl, CURLOPT_URL, "pop3://pop.example.com");
+
+    /* Set the UIDL command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "UIDL");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/postinmemory.c

@@ -0,0 +1,111 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2013, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <curl/curl.h>
+
+struct MemoryStruct {
+  char *memory;
+  size_t size;
+};
+
+static size_t
+WriteMemoryCallback(void *contents, size_t size, size_t nmemb, void *userp)
+{
+  size_t realsize = size * nmemb;
+  struct MemoryStruct *mem = (struct MemoryStruct *)userp;
+
+  mem->memory = realloc(mem->memory, mem->size + realsize + 1);
+  if(mem->memory == NULL) {
+    /* out of memory! */
+    printf("not enough memory (realloc returned NULL)\n");
+    return 0;
+  }
+
+  memcpy(&(mem->memory[mem->size]), contents, realsize);
+  mem->size += realsize;
+  mem->memory[mem->size] = 0;
+
+  return realsize;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res;
+  struct MemoryStruct chunk;
+  static const char *postthis="Field=1&Field=2&Field=3";
+
+  chunk.memory = malloc(1);  /* will be grown as needed by realloc above */
+  chunk.size = 0;    /* no data at this point */
+
+  curl_global_init(CURL_GLOBAL_ALL);
+  curl = curl_easy_init();
+  if(curl) {
+
+    curl_easy_setopt(curl, CURLOPT_URL, "http://www.example.org/");
+
+    /* send all data to this function  */
+    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteMemoryCallback);
+
+    /* we pass our 'chunk' struct to the callback function */
+    curl_easy_setopt(curl, CURLOPT_WRITEDATA, (void *)&chunk);
+
+    /* some servers don't like requests that are made without a user-agent
+       field, so we provide one */
+    curl_easy_setopt(curl, CURLOPT_USERAGENT, "libcurl-agent/1.0");
+
+    curl_easy_setopt(curl, CURLOPT_POSTFIELDS, postthis);
+
+    /* if we don't provide POSTFIELDSIZE, libcurl will strlen() by
+       itself */
+    curl_easy_setopt(curl, CURLOPT_POSTFIELDSIZE, (long)strlen(postthis));
+
+    /* Perform the request, res will get the return code */
+    res = curl_easy_perform(curl);
+    /* Check for errors */
+    if(res != CURLE_OK) {
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+    }
+    else {
+      /*
+       * Now, our chunk.memory points to a memory block that is chunk.size
+       * bytes big and contains the remote file.
+       *
+       * Do something nice with it!
+       */
+      printf("%s\n",chunk.memory);
+    }
+
+    /* always cleanup */
+    curl_easy_cleanup(curl);
+
+    if(chunk.memory)
+      free(chunk.memory);
+
+    /* we're done with libcurl, so clean it up */
+    curl_global_cleanup();
+  }
+  return 0;
+}

docs/examples/progressfunc.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
  *
  * This software is licensed as described in the file COPYING, which
  * you should have received as part of this distribution. The terms
@@ -30,9 +30,10 @@ struct myprogress {
   CURL *curl;
 };
 
-static int progress(void *p,
+/* this is how the CURLOPT_XFERINFOFUNCTION callback works */
-                    double dltotal, double dlnow,
+static int xferinfo(void *p,
-                    double ultotal, double ulnow)
+                    curl_off_t dltotal, curl_off_t dlnow,
+                    curl_off_t ultotal, curl_off_t ulnow)
 {
   struct myprogress *myp = (struct myprogress *)p;
   CURL *curl = myp->curl;
@@ -48,7 +49,9 @@ static int progress(void *p,
     fprintf(stderr, "TOTAL TIME: %f \r\n", curtime);
   }
 
-  fprintf(stderr, "UP: %g of %g  DOWN: %g of %g\r\n",
+  fprintf(stderr, "UP: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T
+          "  DOWN: %" CURL_FORMAT_CURL_OFF_T " of %" CURL_FORMAT_CURL_OFF_T
+          "\r\n",
           ulnow, ultotal, dlnow, dltotal);
 
   if(dlnow > STOP_DOWNLOAD_AFTER_THIS_MANY_BYTES)
@@ -56,6 +59,19 @@ static int progress(void *p,
   return 0;
 }
 
+/* for libcurl older than 7.32.0 (CURLOPT_PROGRESSFUNCTION) */
+static int older_progress(void *p,
+                          double dltotal, double dlnow,
+                          double ultotal, double ulnow)
+{
+  return xferinfo(p,
+                  (curl_off_t)dltotal,
+                  (curl_off_t)dlnow,
+                  (curl_off_t)ultotal,
+                  (curl_off_t)ulnow);
+}
+
+
 int main(void)
 {
   CURL *curl;
@@ -68,9 +84,28 @@ int main(void)
     prog.curl = curl;
 
     curl_easy_setopt(curl, CURLOPT_URL, "http://example.com/");
-    curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, progress);
+
+    curl_easy_setopt(curl, CURLOPT_PROGRESSFUNCTION, older_progress);
     /* pass the struct pointer into the progress function */
     curl_easy_setopt(curl, CURLOPT_PROGRESSDATA, &prog);
+
+#if LIBCURL_VERSION_NUM >= 0x072000
+    /* xferinfo was introduced in 7.32.0, no earlier libcurl versions will
+       compile as they won't have the symbols around.
+
+       If built with a newer libcurl, but running with an older libcurl:
+       curl_easy_setopt() will fail in run-time trying to set the new
+       callback, making the older callback get used.
+
+       New libcurls will prefer the new callback and instead use that one even
+       if both callbacks are set. */
+
+    curl_easy_setopt(curl, CURLOPT_XFERINFOFUNCTION, xferinfo);
+    /* pass the struct pointer into the xferinfo function, note that this is
+       an alias to CURLOPT_PROGRESSDATA */
+    curl_easy_setopt(curl, CURLOPT_XFERINFODATA, &prog);
+#endif
+
     curl_easy_setopt(curl, CURLOPT_NOPROGRESS, 0L);
     res = curl_easy_perform(curl);
 

docs/examples/sepheaders.c

@@ -54,23 +54,22 @@ int main(void)
   curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, write_data);
 
   /* open the files */
-  headerfile = fopen(headerfilename,"w");
+  headerfile = fopen(headerfilename,"wb");
   if (headerfile == NULL) {
     curl_easy_cleanup(curl_handle);
     return -1;
   }
-  bodyfile = fopen(bodyfilename,"w");
+  bodyfile = fopen(bodyfilename,"wb");
   if (bodyfile == NULL) {
     curl_easy_cleanup(curl_handle);
     return -1;
   }
 
-  /* we want the headers to this file handle */
+  /* we want the headers be written to this file handle */
   curl_easy_setopt(curl_handle,   CURLOPT_WRITEHEADER, headerfile);
 
-  /*
+  /* we want the body be written to this file handle instead of stdout */
-   * Notice here that if you want the actual data sent anywhere else but
+  curl_easy_setopt(curl_handle,   CURLOPT_WRITEDATA, bodyfile);
-   * stdout, you should consider using the CURLOPT_WRITEDATA option.  */
 
   /* get it! */
   curl_easy_perform(curl_handle);
@@ -78,6 +77,9 @@ int main(void)
   /* close the header file */
   fclose(headerfile);
 
+  /* close the body file */
+  fclose(bodyfile);
+
   /* cleanup curl stuff */
   curl_easy_cleanup(curl_handle);
 

docs/examples/sessioninfo.c

@@ -0,0 +1,105 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2013, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+
+/* Note that this example currently requires cURL to be linked against
+   GnuTLS (and this program must also be linked against -lgnutls). */
+
+#include <stdio.h>
+
+#include <curl/curl.h>
+#include <gnutls/gnutls.h>
+
+static CURL *curl;
+
+static size_t wrfu(void *ptr, size_t size, size_t nmemb, void *stream)
+{
+  const struct curl_tlssessioninfo *info;
+  unsigned int cert_list_size;
+  const gnutls_datum_t *chainp;
+  CURLcode res;
+
+  (void)stream;
+  (void)ptr;
+
+  res = curl_easy_getinfo(curl, CURLINFO_TLS_SESSION, &info);
+
+  if(!res) {
+    switch(info->backend) {
+    case CURLSSLBACKEND_GNUTLS:
+      /* info->internals is now the gnutls_session_t */
+      chainp = gnutls_certificate_get_peers(info->internals, &cert_list_size);
+      if((chainp) && (cert_list_size)) {
+        unsigned int i;
+
+        for(i = 0; i < cert_list_size; i++) {
+          gnutls_x509_crt_t cert;
+          gnutls_datum_t dn;
+
+          if(GNUTLS_E_SUCCESS == gnutls_x509_crt_init(&cert)) {
+            if(GNUTLS_E_SUCCESS ==
+               gnutls_x509_crt_import(cert, &chainp[i], GNUTLS_X509_FMT_DER)) {
+              if(GNUTLS_E_SUCCESS ==
+                 gnutls_x509_crt_print(cert, GNUTLS_CRT_PRINT_FULL, &dn)) {
+                fprintf(stderr, "Certificate #%d: %.*s", i, dn.size, dn.data);
+
+                gnutls_free(dn.data);
+              }
+            }
+
+            gnutls_x509_crt_deinit(cert);
+          }
+        }
+      }
+      break;
+    case CURLSSLBACKEND_NONE:
+    default:
+      break;
+    }
+  }
+
+  return size * nmemb;
+}
+
+int main(void)
+{
+  curl_global_init(CURL_GLOBAL_DEFAULT);
+
+  curl = curl_easy_init();
+  if(curl) {
+    curl_easy_setopt(curl, CURLOPT_URL, "https://www.example.com/");
+
+    curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, wrfu);
+
+    curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+    curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 0L);
+
+    (void) curl_easy_perform(curl);
+
+    curl_easy_cleanup(curl);
+  }
+
+  curl_global_cleanup();
+
+  return 0;
+}

docs/examples/simplesmtp.c

@@ -1,87 +0,0 @@
-/***************************************************************************
- *                                  _   _ ____  _
- *  Project                     ___| | | |  _ \| |
- *                             / __| | | | |_) | |
- *                            | (__| |_| |  _ <| |___
- *                             \___|\___/|_| \_\_____|
- *
- * Copyright (C) 1998 - 2011, 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
- * are also available at http://curl.haxx.se/docs/copyright.html.
- *
- * You may opt to use, copy, modify, merge, publish, distribute and/or sell
- * copies of the Software, and permit persons to whom the Software is
- * furnished to do so, under the terms of the COPYING file.
- *
- * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
- * KIND, either express or implied.
- *
- ***************************************************************************/
-#include <stdio.h>
-#include <string.h>
-#include <curl/curl.h>
-
-int main(void)
-{
-  CURL *curl;
-  CURLcode res;
-  struct curl_slist *recipients = NULL;
-
-  /* value for envelope reverse-path */
-  static const char *from = "<bradh@example.com>";
-
-  /* this becomes the envelope forward-path */
-  static const char *to = "<bradh@example.net>";
-
-  curl = curl_easy_init();
-  if(curl) {
-    /* this is the URL for your mailserver - you can also use an smtps:// URL
-     * here */
-    curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.net.");
-
-    /* Note that this option isn't strictly required, omitting it will result in
-     * libcurl will sent the MAIL FROM command with no sender data. All
-     * autoresponses should have an empty reverse-path, and should be directed
-     * to the address in the reverse-path which triggered them. Otherwise, they
-     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
-     */
-    curl_easy_setopt(curl, CURLOPT_MAIL_FROM, from);
-
-    /* Note that the CURLOPT_MAIL_RCPT takes a list, not a char array.  */
-    recipients = curl_slist_append(recipients, to);
-    curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
-
-    /* You provide the payload (headers and the body of the message) as the
-     * "data" element. There are two choices, either:
-     * - provide a callback function and specify the function name using the
-     * CURLOPT_READFUNCTION option; or
-     * - just provide a FILE pointer that can be used to read the data from.
-     * The easiest case is just to read from standard input, (which is available
-     * as a FILE pointer) as shown here.
-     */
-    curl_easy_setopt(curl, CURLOPT_READDATA, stdin);
-
-    /* send the message (including headers) */
-    res = curl_easy_perform(curl);
-    /* Check for errors */
-    if(res != CURLE_OK)
-      fprintf(stderr, "curl_easy_perform() failed: %s\n",
-              curl_easy_strerror(res));
-
-    /* free the list of recipients */
-    curl_slist_free_all(recipients);
-
-    /* curl won't send the QUIT command until you call cleanup, so you should be
-     * able to re-use this connection for additional messages (setting
-     * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling
-     * curl_easy_perform() again. It may not be a good idea to keep the
-     * connection open for a very long time though (more than a few minutes may
-     * result in the server timing out the connection), and you do want to clean
-     * up in the end.
-     */
-    curl_easy_cleanup(curl);
-  }
-  return 0;
-}

docs/examples/smtp-expn.c

@@ -0,0 +1,73 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <string.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to expand an email mailing list.
+ *
+ * Notes:
+ *
+ * 1) This example requires libcurl 7.34.0 or above.
+ * 2) Not all email servers support this command.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res;
+  struct curl_slist *recipients = NULL;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* This is the URL for your mailserver */
+    curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
+
+    /* Note that the CURLOPT_MAIL_RCPT takes a list, not a char array  */
+    recipients = curl_slist_append(recipients, "Friends");
+    curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
+
+    /* Set the EXPN command */
+    curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "EXPN");
+
+    /* Perform the custom request */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Free the list of recipients */
+    curl_slist_free_all(recipients);
+
+    /* Curl won't send the QUIT command until you call cleanup, so you should
+     * be able to re-use this connection for additional requests. It may not be
+     * a good idea to keep the connection open for a very long time though
+     * (more than a few minutes may result in the server timing out the
+     * connection) and you do want to clean up in the end.
+     */
+    curl_easy_cleanup(curl);
+  }
+
+  return 0;
+}

docs/examples/smtp-mail.c

@@ -0,0 +1,137 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <string.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to send mail using libcurl's SMTP
+ * capabilities. For an exmaple of using the multi interface please see
+ * smtp-multi.c.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+#define FROM    "<sender@example.org>"
+#define TO      "<addressee@example.net>"
+#define CC      "<info@example.org>"
+
+static const char *payload_text[] = {
+  "Date: Mon, 29 Nov 2010 21:54:29 +1100\r\n",
+  "To: " TO "\r\n",
+  "From: " FROM "(Example User)\r\n",
+  "Cc: " CC "(Another example User)\r\n",
+  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
+  "Subject: SMTP example message\r\n",
+  "\r\n", /* empty line to divide headers from body, see RFC5322 */
+  "The body of the message starts here.\r\n",
+  "\r\n",
+  "It could be a lot of lines, could be MIME encoded, whatever.\r\n",
+  "Check RFC5322.\r\n",
+  NULL
+};
+
+struct upload_status {
+  int lines_read;
+};
+
+static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp)
+{
+  struct upload_status *upload_ctx = (struct upload_status *)userp;
+  const char *data;
+
+  if((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
+    return 0;
+  }
+
+  data = payload_text[upload_ctx->lines_read];
+
+  if(data) {
+    size_t len = strlen(data);
+    memcpy(ptr, data, len);
+    upload_ctx->lines_read++;
+
+    return len;
+  }
+
+  return 0;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+  struct curl_slist *recipients = NULL;
+  struct upload_status upload_ctx;
+
+  upload_ctx.lines_read = 0;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* This is the URL for your mailserver */
+    curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
+
+    /* Note that this option isn't strictly required, omitting it will result in
+     * libcurl sending the MAIL FROM command with empty sender data. All
+     * autoresponses should have an empty reverse-path, and should be directed
+     * to the address in the reverse-path which triggered them. Otherwise, they
+     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
+     */
+    curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
+
+    /* Add two recipients, in this particular case they correspond to the
+     * To: and Cc: addressees in the header, but they could be any kind of
+     * recipient. */
+    recipients = curl_slist_append(recipients, TO);
+    recipients = curl_slist_append(recipients, CC);
+    curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
+
+    /* We're using a callback function to specify the payload (the headers and
+     * body of the message). You could just use the CURLOPT_READDATA option to
+     * specify a FILE pointer to read from. */
+    curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
+    curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
+
+    /* Send the message */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Free the list of recipients */
+    curl_slist_free_all(recipients);
+
+    /* curl won't send the QUIT command until you call cleanup, so you should be
+     * able to re-use this connection for additional messages (setting
+     * CURLOPT_MAIL_FROM and CURLOPT_MAIL_RCPT as required, and calling
+     * curl_easy_perform() again. It may not be a good idea to keep the
+     * connection open for a very long time though (more than a few minutes may
+     * result in the server timing out the connection), and you do want to clean
+     * up in the end.
+     */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/smtp-multi.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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,139 +19,151 @@
  * KIND, either express or implied.
  *
  ***************************************************************************/
-/* This is an example application source code sending SMTP mail using the
- * multi interface.
- */
-
 #include <string.h>
 #include <curl/curl.h>
 
-/*
+/* This is an example showing how to send mail using libcurl's SMTP
- * This is the list of basic details you need to tweak to get things right.
+ * capabilities. It builds on the smtp-mail.c example to demonstrate how to use
+ * libcurl's multi interface.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
  */
-#define USERNAME "user@example.com"
+
-#define PASSWORD "123qwerty"
+#define FROM     "<sender@example.com>"
-#define SMTPSERVER "smtp.example.com"
+#define TO       "<recipient@example.com>"
-#define SMTPPORT ":587" /* it is a colon+port string, but you can set it
+#define CC       "<info@example.com>"
-                           to "" to use the default port */
-#define RECIPIENT "<recipient@example.com>"
-#define MAILFROM "<realuser@example.com>"
 
 #define MULTI_PERFORM_HANG_TIMEOUT 60 * 1000
 
-/* Note that you should include the actual meta data headers here as well if
+static const char *payload_text[] = {
-   you want the mail to have a Subject, another From:, show a To: or whatever
+  "Date: Mon, 29 Nov 2010 21:54:29 +1100\r\n",
-   you think your mail should feature! */
+  "To: " TO "\r\n",
-static const char *text[]={
+  "From: " FROM "(Example User)\r\n",
-  "one\n",
+  "Cc: " CC "(Another example User)\r\n",
-  "two\n",
+  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
-  "three\n",
+  "Subject: SMTP multi example message\r\n",
-  " Hello, this is CURL email SMTP\n",
+  "\r\n", /* empty line to divide headers from body, see RFC5322 */
+  "The body of the message starts here.\r\n",
+  "\r\n",
+  "It could be a lot of lines, could be MIME encoded, whatever.\r\n",
+  "Check RFC5322.\r\n",
   NULL
 };
 
-struct WriteThis {
+struct upload_status {
-  int counter;
+  int lines_read;
 };
 
-static size_t read_callback(void *ptr, size_t size, size_t nmemb, void *userp)
+static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp)
 {
-  struct WriteThis *pooh = (struct WriteThis *)userp;
+  struct upload_status *upload_ctx = (struct upload_status *)userp;
   const char *data;
 
-  if(size*nmemb < 1)
+  if((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
     return 0;
+  }
 
-  data = text[pooh->counter];
+  data = payload_text[upload_ctx->lines_read];
 
   if(data) {
     size_t len = strlen(data);
     memcpy(ptr, data, len);
-    pooh->counter++; /* advance pointer */
+    upload_ctx->lines_read++;
+
     return len;
   }
-  return 0;                         /* no more data left to deliver */
+
+  return 0;
 }
 
 static struct timeval tvnow(void)
 {
-  /*
-  ** time() returns the value of time in seconds since the Epoch.
-  */
   struct timeval now;
+
+  /* time() returns the value of time in seconds since the epoch */
   now.tv_sec = (long)time(NULL);
   now.tv_usec = 0;
+
   return now;
 }
 
 static long tvdiff(struct timeval newer, struct timeval older)
 {
-  return (newer.tv_sec-older.tv_sec)*1000+
+  return (newer.tv_sec - older.tv_sec) * 1000 +
-    (newer.tv_usec-older.tv_usec)/1000;
+    (newer.tv_usec - older.tv_usec) / 1000;
 }
 
 int main(void)
 {
-   CURL *curl;
+  CURL *curl;
-   CURLM *mcurl;
+  CURLM *mcurl;
-   int still_running = 1;
+  int still_running = 1;
-   struct timeval mp_start;
+  struct timeval mp_start;
-   struct WriteThis pooh;
+  struct curl_slist *recipients = NULL;
-   struct curl_slist* rcpt_list = NULL;
+  struct upload_status upload_ctx;
 
-   pooh.counter = 0;
+  upload_ctx.lines_read = 0;
 
-   curl_global_init(CURL_GLOBAL_DEFAULT);
+  curl_global_init(CURL_GLOBAL_DEFAULT);
 
-   curl = curl_easy_init();
+  curl = curl_easy_init();
-   if(!curl)
+  if(!curl)
-     return 1;
+    return 1;
 
-   mcurl = curl_multi_init();
+  mcurl = curl_multi_init();
-   if(!mcurl)
+  if(!mcurl)
-     return 2;
+    return 2;
 
-   rcpt_list = curl_slist_append(rcpt_list, RECIPIENT);
+  /* This is the URL for your mailserver */
-   /* more addresses can be added here
+  curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
-      rcpt_list = curl_slist_append(rcpt_list, "<others@example.com>");
+
+  /* Note that this option isn't strictly required, omitting it will result in
+   * libcurl sending the MAIL FROM command with empty sender data. All
+   * autoresponses should have an empty reverse-path, and should be directed
+   * to the address in the reverse-path which triggered them. Otherwise, they
+   * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
    */
+  curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
 
-   curl_easy_setopt(curl, CURLOPT_URL, "smtp://" SMTPSERVER SMTPPORT);
+  /* Add two recipients, in this particular case they correspond to the
-   curl_easy_setopt(curl, CURLOPT_USERNAME, USERNAME);
+   * To: and Cc: addressees in the header, but they could be any kind of
-   curl_easy_setopt(curl, CURLOPT_PASSWORD, PASSWORD);
+   * recipient. */
-   curl_easy_setopt(curl, CURLOPT_READFUNCTION, read_callback);
+  recipients = curl_slist_append(recipients, TO);
-   curl_easy_setopt(curl, CURLOPT_MAIL_FROM, MAILFROM);
+  recipients = curl_slist_append(recipients, CC);
-   curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, rcpt_list);
+  curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
-   curl_easy_setopt(curl, CURLOPT_USE_SSL, (long)CURLUSESSL_ALL);
-   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
-   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
-   curl_easy_setopt(curl, CURLOPT_READDATA, &pooh);
-   curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
-   curl_easy_setopt(curl, CURLOPT_SSLVERSION, 0L);
-   curl_easy_setopt(curl, CURLOPT_SSL_SESSIONID_CACHE, 0L);
-   curl_multi_add_handle(mcurl, curl);
 
-   mp_start = tvnow();
+  /* We're using a callback function to specify the payload (the headers and
+   * body of the message). You could just use the CURLOPT_READDATA option to
+   * specify a FILE pointer to read from. */
+  curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
+  curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
+  curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
 
-  /* we start some action by calling perform right away */
+  /* Tell the multi stack about our easy handle */
+  curl_multi_add_handle(mcurl, curl);
+
+  /* Record the start time which we can use later */
+  mp_start = tvnow();
+
+  /* We start some action by calling perform right away */
   curl_multi_perform(mcurl, &still_running);
 
   while(still_running) {
     struct timeval timeout;
-    int rc; /* select() return code */
-
     fd_set fdread;
     fd_set fdwrite;
     fd_set fdexcep;
     int maxfd = -1;
+    int rc;
 
     long curl_timeo = -1;
 
+    /* Initialise the file descriptors */
     FD_ZERO(&fdread);
     FD_ZERO(&fdwrite);
     FD_ZERO(&fdexcep);
 
-    /* set a suitable timeout to play around with */
+    /* Set a suitable timeout to play around with */
     timeout.tv_sec = 1;
     timeout.tv_usec = 0;
 
@@ -164,7 +176,7 @@ int main(void)
         timeout.tv_usec = (curl_timeo % 1000) * 1000;
     }
 
-    /* get file descriptors from the transfers */
+    /* Get file descriptors from the transfers */
     curl_multi_fdset(mcurl, &fdread, &fdwrite, &fdexcep, &maxfd);
 
     /* In a real-world program you OF COURSE check the return code of the
@@ -172,32 +184,32 @@ int main(void)
        greater or equal than -1.  We call select(maxfd + 1, ...), specially in
        case of (maxfd == -1), we call select(0, ...), which is basically equal
        to sleep. */
-
     rc = select(maxfd+1, &fdread, &fdwrite, &fdexcep, &timeout);
 
-    if (tvdiff(tvnow(), mp_start) > MULTI_PERFORM_HANG_TIMEOUT) {
+    if(tvdiff(tvnow(), mp_start) > MULTI_PERFORM_HANG_TIMEOUT) {
-      fprintf(stderr, "ABORTING TEST, since it seems "
+      fprintf(stderr,
-              "that it would have run forever.\n");
+              "ABORTING: Since it seems that we would have run forever.\n");
       break;
     }
 
     switch(rc) {
-    case -1:
+    case -1:  /* select error */
-      /* select error */
       break;
-    case 0: /* timeout */
+    case 0:   /* timeout */
-    default: /* action */
+    default:  /* action */
       curl_multi_perform(mcurl, &still_running);
       break;
     }
   }
 
-  curl_slist_free_all(rcpt_list);
+  /* Free the list of recipients */
+  curl_slist_free_all(recipients);
+
+  /* Always cleanup */
   curl_multi_remove_handle(mcurl, curl);
   curl_multi_cleanup(mcurl);
   curl_easy_cleanup(curl);
   curl_global_cleanup();
+
   return 0;
 }
-
-

docs/examples/smtp-ssl.c

@@ -0,0 +1,161 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <string.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to send mail using libcurl's SMTP
+ * capabilities. It builds on the smtp-mail.c example to add authentication
+ * and, more importantly, transport security to protect the authentication
+ * details from being snooped.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
+ */
+
+#define FROM    "<sender@example.org>"
+#define TO      "<addressee@example.net>"
+#define CC      "<info@example.org>"
+
+static const char *payload_text[] = {
+  "Date: Mon, 29 Nov 2010 21:54:29 +1100\r\n",
+  "To: " TO "\r\n",
+  "From: " FROM "(Example User)\r\n",
+  "Cc: " CC "(Another example User)\r\n",
+  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
+  "Subject: SMTP SSL example message\r\n",
+  "\r\n", /* empty line to divide headers from body, see RFC5322 */
+  "The body of the message starts here.\r\n",
+  "\r\n",
+  "It could be a lot of lines, could be MIME encoded, whatever.\r\n",
+  "Check RFC5322.\r\n",
+  NULL
+};
+
+struct upload_status {
+  int lines_read;
+};
+
+static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp)
+{
+  struct upload_status *upload_ctx = (struct upload_status *)userp;
+  const char *data;
+
+  if((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
+    return 0;
+  }
+
+  data = payload_text[upload_ctx->lines_read];
+
+  if(data) {
+    size_t len = strlen(data);
+    memcpy(ptr, data, len);
+    upload_ctx->lines_read++;
+
+    return len;
+  }
+
+  return 0;
+}
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res = CURLE_OK;
+  struct curl_slist *recipients = NULL;
+  struct upload_status upload_ctx;
+
+  upload_ctx.lines_read = 0;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
+    /* This is the URL for your mailserver. Note the use of smtps:// rather
+     * than smtp:// to request a SSL based connection. */
+    curl_easy_setopt(curl, CURLOPT_URL, "smtps://mainserver.example.net");
+
+    /* If you want to connect to a site who isn't using a certificate that is
+     * signed by one of the certs in the CA bundle you have, you can skip the
+     * verification of the server's certificate. This makes the connection
+     * A LOT LESS SECURE.
+     *
+     * If you have a CA cert for the server stored someplace else than in the
+     * default bundle, then the CURLOPT_CAPATH option might come handy for
+     * you. */
+#ifdef SKIP_PEER_VERIFICATION
+    curl_easy_setopt(curl, CURLOPT_SSL_VERIFYPEER, 0L);
+#endif
+
+    /* If the site you're connecting to uses a different host name that what
+     * they have mentioned in their server certificate's commonName (or
+     * subjectAltName) fields, libcurl will refuse to connect. You can skip
+     * this check, but this will make the connection less secure. */
+#ifdef SKIP_HOSTNAME_VERFICATION
+    curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
+#endif
+
+    /* Note that this option isn't strictly required, omitting it will result in
+     * libcurl sending the MAIL FROM command with empty sender data. All
+     * autoresponses should have an empty reverse-path, and should be directed
+     * to the address in the reverse-path which triggered them. Otherwise, they
+     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
+     */
+    curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
+
+    /* Add two recipients, in this particular case they correspond to the
+     * To: and Cc: addressees in the header, but they could be any kind of
+     * recipient. */
+    recipients = curl_slist_append(recipients, TO);
+    recipients = curl_slist_append(recipients, CC);
+    curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
+
+    /* We're using a callback function to specify the payload (the headers and
+     * body of the message). You could just use the CURLOPT_READDATA option to
+     * specify a FILE pointer to read from. */
+    curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
+    curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
+
+    /* Since the traffic will be encrypted, it is very useful to turn on debug
+     * information within libcurl to see what is happening during the
+     * transfer */
+    curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
+
+    /* Send the message */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Free the list of recipients */
+    curl_slist_free_all(recipients);
+
+    /* Always cleanup */
+    curl_easy_cleanup(curl);
+  }
+
+  return (int)res;
+}

docs/examples/smtp-tls.c

@@ -5,7 +5,7 @@
  *                            | (__| |_| |  _ <| |___
  *                             \___|\___/|_| \_\_____|
  *
- * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+ * Copyright (C) 1998 - 2014, 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,26 +24,29 @@
 #include <curl/curl.h>
 
 /* This is a simple example showing how to send mail using libcurl's SMTP
- * capabilities. It builds on the simplesmtp.c example, adding some
+ * capabilities. It builds on the smtp-mail.c example to add authentication
- * authentication and transport security.
+ * and, more importantly, transport security to protect the authentication
+ * details from being snooped.
+ *
+ * Note that this example requires libcurl 7.20.0 or above.
  */
 
 #define FROM    "<sender@example.org>"
 #define TO      "<addressee@example.net>"
 #define CC      "<info@example.org>"
 
-static const char *payload_text[]={
+static const char *payload_text[] = {
-  "Date: Mon, 29 Nov 2010 21:54:29 +1100\n",
+  "Date: Mon, 29 Nov 2010 21:54:29 +1100\r\n",
-  "To: " TO "\n",
+  "To: " TO "\r\n",
-  "From: " FROM "(Example User)\n",
+  "From: " FROM "(Example User)\r\n",
-  "Cc: " CC "(Another example User)\n",
+  "Cc: " CC "(Another example User)\r\n",
-  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\n",
+  "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
-  "Subject: SMTP TLS example message\n",
+  "Subject: SMTP TLS example message\r\n",
-  "\n", /* empty line to divide headers from body, see RFC5322 */
+  "\r\n", /* empty line to divide headers from body, see RFC5322 */
-  "The body of the message starts here.\n",
+  "The body of the message starts here.\r\n",
-  "\n",
+  "\r\n",
-  "It could be a lot of lines, could be MIME encoded, whatever.\n",
+  "It could be a lot of lines, could be MIME encoded, whatever.\r\n",
-  "Check RFC5322.\n",
+  "Check RFC5322.\r\n",
   NULL
 };
 
@@ -56,33 +59,38 @@ static size_t payload_source(void *ptr, size_t size, size_t nmemb, void *userp)
   struct upload_status *upload_ctx = (struct upload_status *)userp;
   const char *data;
 
-  if ((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
+  if((size == 0) || (nmemb == 0) || ((size*nmemb) < 1)) {
     return 0;
   }
 
   data = payload_text[upload_ctx->lines_read];
 
-  if (data) {
+  if(data) {
     size_t len = strlen(data);
     memcpy(ptr, data, len);
-    upload_ctx->lines_read ++;
+    upload_ctx->lines_read++;
+
     return len;
   }
+
   return 0;
 }
 
-
 int main(void)
 {
   CURL *curl;
-  CURLcode res;
+  CURLcode res = CURLE_OK;
   struct curl_slist *recipients = NULL;
   struct upload_status upload_ctx;
 
   upload_ctx.lines_read = 0;
 
   curl = curl_easy_init();
-  if (curl) {
+  if(curl) {
+    /* Set username and password */
+    curl_easy_setopt(curl, CURLOPT_USERNAME, "user");
+    curl_easy_setopt(curl, CURLOPT_PASSWORD, "secret");
+
     /* This is the URL for your mailserver. Note the use of port 587 here,
      * instead of the normal SMTP port (25). Port 587 is commonly used for
      * secure mail submission (see RFC4403), but you should use whatever
@@ -106,18 +114,17 @@ int main(void)
      * Instead, you should get the issuer certificate (or the host certificate
      * if the certificate is self-signed) and add it to the set of certificates
      * that are known to libcurl using CURLOPT_CAINFO and/or CURLOPT_CAPATH. See
-     * docs/SSLCERTS for more information.
+     * docs/SSLCERTS for more information. */
-     */
     curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem");
 
-    /* A common reason for requiring transport security is to protect
+    /* Note that this option isn't strictly required, omitting it will result in
-     * authentication details (user names and passwords) from being "snooped"
+     * libcurl sending the MAIL FROM command with empty sender data. All
-     * on the network. Here is how the user name and password are provided: */
+     * autoresponses should have an empty reverse-path, and should be directed
-    curl_easy_setopt(curl, CURLOPT_USERNAME, "user@example.net");
+     * to the address in the reverse-path which triggered them. Otherwise, they
-    curl_easy_setopt(curl, CURLOPT_PASSWORD, "P@ssw0rd");
+     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
-
+     */
-    /* value for envelope reverse-path */
     curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
+
     /* Add two recipients, in this particular case they correspond to the
      * To: and Cc: addressees in the header, but they could be any kind of
      * recipient. */
@@ -125,28 +132,32 @@ int main(void)
     recipients = curl_slist_append(recipients, CC);
     curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
 
-    /* In this case, we're using a callback function to specify the data. You
+    /* We're using a callback function to specify the payload (the headers and
-     * could just use the CURLOPT_READDATA option to specify a FILE pointer to
+     * body of the message). You could just use the CURLOPT_READDATA option to
-     * read from.
+     * specify a FILE pointer to read from. */
-     */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
     curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
+    curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
 
     /* Since the traffic will be encrypted, it is very useful to turn on debug
      * information within libcurl to see what is happening during the transfer.
      */
     curl_easy_setopt(curl, CURLOPT_VERBOSE, 1L);
 
-    /* send the message (including headers) */
+    /* Send the message */
     res = curl_easy_perform(curl);
+
     /* Check for errors */
     if(res != CURLE_OK)
       fprintf(stderr, "curl_easy_perform() failed: %s\n",
               curl_easy_strerror(res));
 
-    /* free the list of recipients and clean up */
+    /* Free the list of recipients */
     curl_slist_free_all(recipients);
+
+    /* Always cleanup */
     curl_easy_cleanup(curl);
   }
-  return 0;
+
+  return (int)res;
 }

docs/examples/smtp-vrfy.c

@@ -0,0 +1,73 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2014, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+#include <stdio.h>
+#include <string.h>
+#include <curl/curl.h>
+
+/* This is a simple example showing how to verify an email address from an
+ * SMTP server.
+ *
+ * Notes:
+ *
+ * 1) This example requires libcurl 7.34.0 or above.
+ * 2) Not all email servers support this command and even if your email server
+ *    does support it, it may respond with a 252 response code even though the
+ *    address doesn't exist.
+ */
+
+int main(void)
+{
+  CURL *curl;
+  CURLcode res;
+  struct curl_slist *recipients = NULL;
+
+  curl = curl_easy_init();
+  if(curl) {
+    /* This is the URL for your mailserver */
+    curl_easy_setopt(curl, CURLOPT_URL, "smtp://mail.example.com");
+
+    /* Note that the CURLOPT_MAIL_RCPT takes a list, not a char array  */
+    recipients = curl_slist_append(recipients, "<recipient@example.com>");
+    curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
+
+    /* Perform the VRFY */
+    res = curl_easy_perform(curl);
+
+    /* Check for errors */
+    if(res != CURLE_OK)
+      fprintf(stderr, "curl_easy_perform() failed: %s\n",
+              curl_easy_strerror(res));
+
+    /* Free the list of recipients */
+    curl_slist_free_all(recipients);
+
+    /* Curl won't send the QUIT command until you call cleanup, so you should
+     * be able to re-use this connection for additional requests. It may not be
+     * a good idea to keep the connection open for a very long time though
+     * (more than a few minutes may result in the server timing out the
+     * connection) and you do want to clean up in the end.
+     */
+    curl_easy_cleanup(curl);
+  }
+
+  return 0;
+}

docs/examples/usercertinmem.c

@@ -0,0 +1,224 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 2013, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+/* Example using an in memory PEM user certificate and RSA key to retrieve an
+ * https page.
+ * Written by Ishan SinghLevett, based on Theo Borm's cacertinmem.c.
+ * Note that to maintain simplicity this example does not use a CA certificate 
+ * for peer verification.  However, some form of peer verification
+ * must be used in real circumstances when a secure connection is required.
+ */
+
+#include <openssl/ssl.h>
+#include <openssl/x509.h>
+#include <openssl/pem.h>
+#include <curl/curl.h>
+#include <stdio.h>
+
+static size_t writefunction(void *ptr, size_t size, size_t nmemb, void *stream)
+{
+  fwrite(ptr,size,nmemb,stream);
+  return(nmemb*size);
+}
+
+static CURLcode sslctx_function(CURL *curl, void *sslctx, void *parm)
+{
+  X509 *cert = NULL;
+  BIO *bio = NULL;
+  BIO *kbio = NULL;
+  RSA *rsa = NULL;
+  int ret;
+
+  const char *mypem = /* www.cacert.org */
+    "-----BEGIN CERTIFICATE-----\n"\
+    "MIIHPTCCBSWgAwIBAgIBADANBgkqhkiG9w0BAQQFADB5MRAwDgYDVQQKEwdSb290\n"\
+    "IENBMR4wHAYDVQQLExVodHRwOi8vd3d3LmNhY2VydC5vcmcxIjAgBgNVBAMTGUNB\n"\
+    "IENlcnQgU2lnbmluZyBBdXRob3JpdHkxITAfBgkqhkiG9w0BCQEWEnN1cHBvcnRA\n"\
+    "Y2FjZXJ0Lm9yZzAeFw0wMzAzMzAxMjI5NDlaFw0zMzAzMjkxMjI5NDlaMHkxEDAO\n"\
+    "BgNVBAoTB1Jvb3QgQ0ExHjAcBgNVBAsTFWh0dHA6Ly93d3cuY2FjZXJ0Lm9yZzEi\n"\
+    "MCAGA1UEAxMZQ0EgQ2VydCBTaWduaW5nIEF1dGhvcml0eTEhMB8GCSqGSIb3DQEJ\n"\
+    "ARYSc3VwcG9ydEBjYWNlcnQub3JnMIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIIC\n"\
+    "CgKCAgEAziLA4kZ97DYoB1CW8qAzQIxL8TtmPzHlawI229Z89vGIj053NgVBlfkJ\n"\
+    "8BLPRoZzYLdufujAWGSuzbCtRRcMY/pnCujW0r8+55jE8Ez64AO7NV1sId6eINm6\n"\
+    "zWYyN3L69wj1x81YyY7nDl7qPv4coRQKFWyGhFtkZip6qUtTefWIonvuLwphK42y\n"\
+    "fk1WpRPs6tqSnqxEQR5YYGUFZvjARL3LlPdCfgv3ZWiYUQXw8wWRBB0bF4LsyFe7\n"\
+    "w2t6iPGwcswlWyCR7BYCEo8y6RcYSNDHBS4CMEK4JZwFaz+qOqfrU0j36NK2B5jc\n"\
+    "G8Y0f3/JHIJ6BVgrCFvzOKKrF11myZjXnhCLotLddJr3cQxyYN/Nb5gznZY0dj4k\n"\
+    "epKwDpUeb+agRThHqtdB7Uq3EvbXG4OKDy7YCbZZ16oE/9KTfWgu3YtLq1i6L43q\n"\
+    "laegw1SJpfvbi1EinbLDvhG+LJGGi5Z4rSDTii8aP8bQUWWHIbEZAWV/RRyH9XzQ\n"\
+    "QUxPKZgh/TMfdQwEUfoZd9vUFBzugcMd9Zi3aQaRIt0AUMyBMawSB3s42mhb5ivU\n"\
+    "fslfrejrckzzAeVLIL+aplfKkQABi6F1ITe1Yw1nPkZPcCBnzsXWWdsC4PDSy826\n"\
+    "YreQQejdIOQpvGQpQsgi3Hia/0PsmBsJUUtaWsJx8cTLc6nloQsCAwEAAaOCAc4w\n"\
+    "ggHKMB0GA1UdDgQWBBQWtTIb1Mfz4OaO873SsDrusjkY0TCBowYDVR0jBIGbMIGY\n"\
+    "gBQWtTIb1Mfz4OaO873SsDrusjkY0aF9pHsweTEQMA4GA1UEChMHUm9vdCBDQTEe\n"\
+    "MBwGA1UECxMVaHR0cDovL3d3dy5jYWNlcnQub3JnMSIwIAYDVQQDExlDQSBDZXJ0\n"\
+    "IFNpZ25pbmcgQXV0aG9yaXR5MSEwHwYJKoZIhvcNAQkBFhJzdXBwb3J0QGNhY2Vy\n"\
+    "dC5vcmeCAQAwDwYDVR0TAQH/BAUwAwEB/zAyBgNVHR8EKzApMCegJaAjhiFodHRw\n"\
+    "czovL3d3dy5jYWNlcnQub3JnL3Jldm9rZS5jcmwwMAYJYIZIAYb4QgEEBCMWIWh0\n"\
+    "dHBzOi8vd3d3LmNhY2VydC5vcmcvcmV2b2tlLmNybDA0BglghkgBhvhCAQgEJxYl\n"\
+    "aHR0cDovL3d3dy5jYWNlcnQub3JnL2luZGV4LnBocD9pZD0xMDBWBglghkgBhvhC\n"\
+    "AQ0ESRZHVG8gZ2V0IHlvdXIgb3duIGNlcnRpZmljYXRlIGZvciBGUkVFIGhlYWQg\n"\
+    "b3ZlciB0byBodHRwOi8vd3d3LmNhY2VydC5vcmcwDQYJKoZIhvcNAQEEBQADggIB\n"\
+    "ACjH7pyCArpcgBLKNQodgW+JapnM8mgPf6fhjViVPr3yBsOQWqy1YPaZQwGjiHCc\n"\
+    "nWKdpIevZ1gNMDY75q1I08t0AoZxPuIrA2jxNGJARjtT6ij0rPtmlVOKTV39O9lg\n"\
+    "18p5aTuxZZKmxoGCXJzN600BiqXfEVWqFcofN8CCmHBh22p8lqOOLlQ+TyGpkO/c\n"\
+    "gr/c6EWtTZBzCDyUZbAEmXZ/4rzCahWqlwQ3JNgelE5tDlG+1sSPypZt90Pf6DBl\n"\
+    "Jzt7u0NDY8RD97LsaMzhGY4i+5jhe1o+ATc7iwiwovOVThrLm82asduycPAtStvY\n"\
+    "sONvRUgzEv/+PDIqVPfE94rwiCPCR/5kenHA0R6mY7AHfqQv0wGP3J8rtsYIqQ+T\n"\
+    "SCX8Ev2fQtzzxD72V7DX3WnRBnc0CkvSyqD/HMaMyRa+xMwyN2hzXwj7UfdJUzYF\n"\
+    "CpUCTPJ5GhD22Dp1nPMd8aINcGeGG7MW9S/lpOt5hvk9C8JzC6WZrG/8Z7jlLwum\n"\
+    "GCSNe9FINSkYQKyTYOGWhlC0elnYjyELn8+CkcY7v2vcB5G5l1YjqrZslMZIBjzk\n"\
+    "zk6q5PYvCdxTby78dOs6Y5nCpqyJvKeyRKANihDjbPIky/qbn3BHLt4Ui9SyIAmW\n"\
+    "omTxJBzcoTWcFbLUvFUufQb1nA5V9FrWk9p2rSVzTMVD\n"\
+    "-----END CERTIFICATE-----\n";
+
+/*replace the XXX with the actual RSA key*/
+  const char *mykey =
+    "-----BEGIN RSA PRIVATE KEY-----\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n"\
+    "-----END RSA PRIVATE KEY-----\n";
+
+  (void)curl; /* avoid warnings */
+  (void)parm; /* avoid warnings */
+
+  /* get a BIO */
+  bio = BIO_new_mem_buf((char *)mypem, -1);
+
+  if (bio == NULL) {
+    printf("BIO_new_mem_buf failed\n");
+  }
+
+  /* use it to read the PEM formatted certificate from memory into an X509
+   * structure that SSL can use
+   */
+  cert = PEM_read_bio_X509(bio, NULL, 0, NULL);
+  if (cert == NULL) {
+    printf("PEM_read_bio_X509 failed...\n");
+  }
+
+  /*tell SSL to use the X509 certificate*/
+  ret = SSL_CTX_use_certificate((SSL_CTX*)sslctx, cert);
+  if (ret != 1) {
+    printf("Use certificate failed\n");
+  }
+
+  /*create a bio for the RSA key*/
+  kbio = BIO_new_mem_buf((char *)mykey, -1);
+  if (kbio == NULL) {
+    printf("BIO_new_mem_buf failed\n");
+  }
+
+  /*read the key bio into an RSA object*/
+  rsa = PEM_read_bio_RSAPrivateKey(kbio, NULL, 0, NULL);
+  if (rsa == NULL) {
+    printf("Failed to create key bio\n");
+  }
+
+  /*tell SSL to use the RSA key from memory*/
+  ret = SSL_CTX_use_RSAPrivateKey((SSL_CTX*)sslctx, rsa);
+  if (ret != 1) {
+    printf("Use Key failed\n");
+  }
+
+  /* free resources that have been allocated by openssl functions */
+  if (bio)
+    BIO_free(bio);
+
+  if (kbio)
+    BIO_free(kbio);
+
+  if (rsa)
+    RSA_free(rsa);
+
+  if (cert)
+    X509_free(cert);
+
+  /* all set to go */
+  return CURLE_OK ;
+}
+
+int main(void)
+{
+  CURL *ch;
+  CURLcode rv;
+
+  rv = curl_global_init(CURL_GLOBAL_ALL);
+  ch = curl_easy_init();
+  rv = curl_easy_setopt(ch,CURLOPT_VERBOSE, 0L);
+  rv = curl_easy_setopt(ch,CURLOPT_HEADER, 0L);
+  rv = curl_easy_setopt(ch,CURLOPT_NOPROGRESS, 1L);
+  rv = curl_easy_setopt(ch,CURLOPT_NOSIGNAL, 1L);
+  rv = curl_easy_setopt(ch,CURLOPT_WRITEFUNCTION, *writefunction);
+  rv = curl_easy_setopt(ch,CURLOPT_WRITEDATA, stdout);
+  rv = curl_easy_setopt(ch,CURLOPT_HEADERFUNCTION, *writefunction);
+  rv = curl_easy_setopt(ch,CURLOPT_WRITEHEADER, stderr);
+  rv = curl_easy_setopt(ch,CURLOPT_SSLCERTTYPE,"PEM");
+
+  /* both VERIFYPEER and VERIFYHOST are set to 0 in this case because there is
+     no CA certificate*/
+
+  rv = curl_easy_setopt(ch,CURLOPT_SSL_VERIFYPEER, 0L);
+  rv = curl_easy_setopt(ch,CURLOPT_SSL_VERIFYHOST, 0L);
+  rv = curl_easy_setopt(ch, CURLOPT_URL, "https://www.example.com/");
+  rv = curl_easy_setopt(ch, CURLOPT_SSLKEYTYPE, "PEM");
+
+  /* first try: retrieve page without user certificate and key -> will fail
+   */
+  rv = curl_easy_perform(ch);
+  if (rv==CURLE_OK) {
+    printf("*** transfer succeeded ***\n");
+  }
+  else {
+    printf("*** transfer failed ***\n");
+  }
+
+  /* second try: retrieve page using user certificate and key -> will succeed
+   * load the certificate and key by installing a function doing the necessary
+   * "modifications" to the SSL CONTEXT just before link init
+   */
+  rv = curl_easy_setopt(ch,CURLOPT_SSL_CTX_FUNCTION, *sslctx_function);
+  rv = curl_easy_perform(ch);
+  if (rv==CURLE_OK) {
+    printf("*** transfer succeeded ***\n");
+  }
+  else {
+    printf("*** transfer failed ***\n");
+  }
+
+  curl_easy_cleanup(ch);
+  curl_global_cleanup();
+  return rv;
+}

docs/examples/xmlstream.c

@@ -0,0 +1,158 @@
+/***************************************************************************
+ *                                  _   _ ____  _
+ *  Project                     ___| | | |  _ \| |
+ *                             / __| | | | |_) | |
+ *                            | (__| |_| |  _ <| |___
+ *                             \___|\___/|_| \_\_____|
+ *
+ * Copyright (C) 1998 - 2013, 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
+ * are also available at http://curl.haxx.se/docs/copyright.html.
+ *
+ * You may opt to use, copy, modify, merge, publish, distribute and/or sell
+ * copies of the Software, and permit persons to whom the Software is
+ * furnished to do so, under the terms of the COPYING file.
+ *
+ * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
+ * KIND, either express or implied.
+ *
+ ***************************************************************************/
+/* Stream-parse a document using the streaming Expat parser.
+ * Written by David Strauss
+ *
+ * Expat => http://www.libexpat.org/
+ *
+ * gcc -Wall -I/usr/local/include xmlstream.c -lcurl -lexpat -o xmlstream
+ *
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <assert.h>
+
+#include <expat.h>
+#include <curl/curl.h>
+
+struct MemoryStruct {
+  char *memory;
+  size_t size;
+};
+
+struct ParserStruct {
+  int ok;
+  size_t tags;
+  size_t depth;
+  struct MemoryStruct characters;
+};
+
+static void startElement(void *userData, const XML_Char *name, const XML_Char **atts)
+{
+  struct ParserStruct *state = (struct ParserStruct *) userData;
+  state->tags++;
+  state->depth++;
+
+  /* Get a clean slate for reading in character data. */
+  free(state->characters.memory);
+  state->characters.memory = NULL;
+  state->characters.size = 0;
+}
+
+static void characterDataHandler(void *userData, const XML_Char *s, int len)
+{
+  struct ParserStruct *state = (struct ParserStruct *) userData;
+  struct MemoryStruct *mem = &state->characters;
+
+  mem->memory = realloc(mem->memory, mem->size + len + 1);
+  if(mem->memory == NULL) {
+    /* Out of memory. */
+    fprintf(stderr, "Not enough memory (realloc returned NULL).\n");
+    state->ok = 0;
+    return;
+  }
+
+  memcpy(&(mem->memory[mem->size]), s, len);
+  mem->size += len;
+  mem->memory[mem->size] = 0;
+}
+
+static void endElement(void *userData, const XML_Char *name)
+{
+  struct ParserStruct *state = (struct ParserStruct *) userData;
+  state->depth--;
+
+  printf("%5lu   %10lu   %s\n", state->depth, state->characters.size, name);
+}
+
+static size_t parseStreamCallback(void *contents, size_t length, size_t nmemb, void *userp)
+{
+  XML_Parser parser = (XML_Parser) userp;
+  size_t real_size = length * nmemb;
+  struct ParserStruct *state = (struct ParserStruct *) XML_GetUserData(parser);
+
+  /* Only parse if we're not already in a failure state. */
+  if (state->ok && XML_Parse(parser, contents, real_size, 0) == 0) {
+    int error_code = XML_GetErrorCode(parser);
+    fprintf(stderr, "Parsing response buffer of length %lu failed with error code %d (%s).\n",
+            real_size, error_code, XML_ErrorString(error_code));
+    state->ok = 0;
+  }
+
+  return real_size;
+}
+
+int main(void)
+{
+  CURL *curl_handle;
+  CURLcode res;
+  XML_Parser parser;
+  struct ParserStruct state;
+
+  /* Initialize the state structure for parsing. */
+  memset(&state, 0, sizeof(struct ParserStruct));
+  state.ok = 1;
+
+  /* Initialize a namespace-aware parser. */
+  parser = XML_ParserCreateNS(NULL, '\0');
+  XML_SetUserData(parser, &state);
+  XML_SetElementHandler(parser, startElement, endElement);
+  XML_SetCharacterDataHandler(parser, characterDataHandler);
+
+  /* Initalize a libcurl handle. */
+  curl_global_init(CURL_GLOBAL_ALL ^ CURL_GLOBAL_SSL);
+  curl_handle = curl_easy_init();
+  curl_easy_setopt(curl_handle, CURLOPT_URL, "http://www.w3schools.com/xml/simple.xml");
+  curl_easy_setopt(curl_handle, CURLOPT_WRITEFUNCTION, parseStreamCallback);
+  curl_easy_setopt(curl_handle, CURLOPT_WRITEDATA, (void *)parser);
+
+  printf("Depth   Characters   Closing Tag\n");
+
+  /* Perform the request and any follow-up parsing. */
+  res = curl_easy_perform(curl_handle);
+  if(res != CURLE_OK) {
+    fprintf(stderr, "curl_easy_perform() failed: %s\n",
+            curl_easy_strerror(res));
+  }
+  else if (state.ok) {
+    /* Expat requires one final call to finalize parsing. */
+    if (XML_Parse(parser, NULL, 0, 1) == 0) {
+      int error_code = XML_GetErrorCode(parser);
+      fprintf(stderr, "Finalizing parsing failed with error code %d (%s).\n",
+              error_code, XML_ErrorString(error_code));
+    }
+    else {
+      printf("                     --------------\n");
+      printf("                     %lu tags total\n", state.tags);
+    }
+  }
+
+  /* Clean up. */
+  free(state.characters.memory);
+  XML_ParserFree(parser);
+  curl_easy_cleanup(curl_handle);
+  curl_global_cleanup();
+
+  return 0;
+}

docs/libcurl/Makefile.am

@@ -79,9 +79,12 @@ PDFPAGES = curl_easy_cleanup.pdf curl_easy_getinfo.pdf			 \
  curl_multi_assign.pdf curl_easy_pause.pdf curl_easy_recv.pdf		 \
  curl_easy_send.pdf curl_multi_socket_action.pdf curl_multi_wait.pdf
 
+m4macrodir = $(datadir)/aclocal
+dist_m4macro_DATA = libcurl.m4
+
 CLEANFILES = $(HTMLPAGES) $(PDFPAGES)
 
-EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) libcurl.m4 ABI \
+EXTRA_DIST = $(man_MANS) $(HTMLPAGES) index.html $(PDFPAGES) ABI \
   symbols-in-versions symbols.pl
 MAN2HTML= roffit --mandir=. < $< >$@
 

docs/libcurl/curl_easy_getinfo.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, 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
@@ -109,7 +109,9 @@ uploaded.
 .IP CURLINFO_SIZE_DOWNLOAD
 Pass a pointer to a double to receive the total amount of bytes that were
 downloaded. The amount is only for the latest transfer and will be reset again
-for each new transfer.
+for each new transfer. This counts actual payload data, what's also commonly
+called body. All meta and header data are excluded and will not be counted in
+this number.
 .IP CURLINFO_SPEED_DOWNLOAD
 Pass a pointer to a double to receive the average download speed that curl
 measured for the complete download. Measured in bytes/second.
@@ -219,8 +221,20 @@ done. The struct reports how many certs it found and then you can extract info
 for each of those certs by following the linked lists. The info chain is
 provided in a series of data in the format "name:content" where the content is
 for the specific named data. See also the certinfo.c example. NOTE: this
-option is only available in libcurl built with OpenSSL support. (Added in
+option is only available in libcurl built with OpenSSL, NSS, GSKit or QsoSSL
-7.19.1)
+support. (Added in 7.19.1)
+.IP CURLINFO_TLS_SESSION
+Pass a pointer to a 'struct curl_tlsinfo *'.  The pointer will be initialized
+to refer to a 'struct curl_tlsinfo *' that will contain an enum indicating the
+SSL library used for the handshake and the respective internal TLS session
+structure of this underlying SSL library.
+
+This may then be used to extract certificate information in a format
+convenient for further processing, such as manual validation. NOTE: this
+option may not be available for all SSL backends; unsupported SSL backends
+will return 'CURLSSLBACKEND_NONE' to indicate that they are not supported;
+this does not mean that no SSL backend was used. (Added in 7.34.0)
+
 .IP CURLINFO_CONDITION_UNMET
 Pass a pointer to a long to receive the number 1 if the condition provided in
 the previous request didn't match (see \fICURLOPT_TIMECONDITION\fP). Alas, if
@@ -232,7 +246,7 @@ Pass a pointer to a char pointer to receive a pointer to a string holding the
 most recent RTSP Session ID.
 
 Applications wishing to resume an RTSP session on another connection should
-retreive this info before closing the active connection.
+retrieve this info before closing the active connection.
 .IP CURLINFO_RTSP_CLIENT_CSEQ
 Pass a pointer to a long to receive the next CSeq that will be used by the
 application.
@@ -244,7 +258,7 @@ by the application.
 unimplemented).\fP
 
 Applications wishing to resume an RTSP session on another connection should
-retreive this info before closing the active connection.
+retrieve this info before closing the active connection.
 .IP CURLINFO_RTSP_CSEQ_RECV
 Pass a pointer to a long to receive the most recently received CSeq from the
 server. If your application encounters a \fICURLE_RTSP_CSEQ_ERROR\fP then you

docs/libcurl/curl_easy_pause.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2013, 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
@@ -31,15 +31,18 @@ curl_easy_pause - pause and unpause a connection
 Using this function, you can explicitly mark a running connection to get
 paused, and you can unpause a connection that was previously paused.
 
-A connection can be paused by using this function or by letting the read
+A connection can be paused by using this function or by letting the read or
-or the write callbacks return the proper magic return code
+the write callbacks return the proper magic return code
 (\fICURL_READFUNC_PAUSE\fP and \fICURL_WRITEFUNC_PAUSE\fP). A write callback
 that returns pause signals to the library that it couldn't take care of any
 data at all, and that data will then be delivered again to the callback when
 the writing is later unpaused.
 
-NOTE: while it may feel tempting, take care and notice that you cannot call
+While it may feel tempting, take care and notice that you cannot call this
-this function from another thread.
+function from another thread. To unpause, you may for example call it from the
+progress callback (see \fIcurl_easy_setopt(3)\fP's
+\fICURLOPT_PROGRESSFUNCTION\fP), which gets called at least once per second,
+even if the connection is paused.
 
 When this function is called to unpause reading, the chance is high that you
 will get your write callback called before this function returns.
@@ -65,9 +68,25 @@ Convenience define that unpauses both directions
 CURLE_OK (zero) means that the option was set properly, and a non-zero return
 code means something wrong occurred after the new state was set.  See the
 \fIlibcurl-errors(3)\fP man page for the full list with descriptions.
+.SH LIMITATIONS
+The pausing of transfers does not work with protocols that work without
+network connectivity, like FILE://. Trying to pause such a transfer, in any
+direction, will cause problems in the worst case or an error in the best case.
 .SH AVAILABILITY
 This function was added in libcurl 7.18.0. Before this version, there was no
 explicit support for pausing transfers.
+.SH "USAGE WITH THE MULTI-SOCKET INTERFACE"
+Before libcurl 7.32.0, when a specific handle was unpaused with this function,
+there was no particular forced rechecking or similar of the socket's state,
+which made the continuation of the transfer get delayed until next
+multi-socket call invoke or even longer. Alternatively, the user could
+forcibly call for example curl_multi_socket_all(3) - with a rather hefty
+performance penalty.
+
+Starting in libcurl 7.32.0, unpausing a transfer will schedule a timeout
+trigger for that handle 1 millisecond into the future, so that a
+curl_multi_socket_action( ... CURL_SOCKET_TIMEOUT) can be used immediately
+afterwards to get the transfer going again as desired.
 .SH "MEMORY USE"
 When pausing a read by returning the magic return code from a write callback,
 the read data is already in libcurl's internal buffers so it'll have to keep

docs/libcurl/curl_easy_perform.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, 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
@@ -25,33 +25,41 @@ curl_easy_perform - Perform a file transfer
 .SH SYNOPSIS
 .B #include <curl/curl.h>
 .sp
-.BI "CURLcode curl_easy_perform(CURL *" handle ");"
+.BI "CURLcode curl_easy_perform(CURL *" easy_handle ");"
 .ad
 .SH DESCRIPTION
-This function is called after the init and all the \fIcurl_easy_setopt(3)\fP
+Invoke this function after \fIcurl_easy_init(3)\fP and all the
-calls are made, and will perform the transfer as described in the options.  It
+\fIcurl_easy_setopt(3)\fP calls are made, and will perform the transfer as
-must be called with the same
+described in the options. It must be called with the same \fBeasy_handle\fP as
-.I handle
+input as the \fIcurl_easy_init(3)\fP call returned.
-as input as the curl_easy_init call returned.
+
+\fIcurl_easy_perform(3)\fP performs the entire request in a blocking manner
+and returns when done, or if it failed. For non-blocking behavior, see
+\fIcurl_multi_perform(3)\fP.
 
 You can do any amount of calls to \fIcurl_easy_perform(3)\fP while using the
-same handle. If you intend to transfer more than one file, you are even
+same \fBeasy_handle\fP. If you intend to transfer more than one file, you are
-encouraged to do so. libcurl will then attempt to re-use the same connection
+even encouraged to do so. libcurl will then attempt to re-use the same
-for the following transfers, thus making the operations faster, less CPU
+connection for the following transfers, thus making the operations faster,
-intense and using less network resources. Just note that you will have to use
+less CPU intense and using less network resources. Just note that you will
-\fIcurl_easy_setopt(3)\fP between the invokes to set options for the following
+have to use \fIcurl_easy_setopt(3)\fP between the invokes to set options for
-curl_easy_perform.
+the following curl_easy_perform.
 
 You must never call this function simultaneously from two places using the
-same handle. Let the function return first before invoking it another time. If
+same \fBeasy_handle\fP. Let the function return first before invoking it
-you want parallel transfers, you must use several curl handles.
+another time. If you want parallel transfers, you must use several curl
+easy_handles.
+
+While the \fBeasy_handle\fP is added to a multi handle, it cannot be used by
+\fIcurl_easy_perform(3)\fP.
 .SH RETURN VALUE
-0 means everything was ok, non-zero means an error occurred as
+CURLE_OK (0) means everything was ok, non-zero means an error occurred as
 .I <curl/curl.h>
-defines. If the CURLOPT_ERRORBUFFER was set with
+defines - see \fIlibcurl-errors(3)\fP. If the \fBCURLOPT_ERRORBUFFER\fP was
-.I curl_easy_setopt
+set with \fIcurl_easy_setopt(3)\fP there will be a readable error message in
-there will be a readable error message in the error buffer when non-zero is
+the error buffer when non-zero is returned.
-returned.
 .SH "SEE ALSO"
 .BR curl_easy_init "(3), " curl_easy_setopt "(3), "
+.BR curl_multi_add_handle "(3), " curl_multi_perform "(3), "
+.BR libcurl-errors "(3), "
 

docs/libcurl/curl_easy_setopt.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2012, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, 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
@@ -58,7 +58,8 @@ The \fIhandle\fP is the return code from a \fIcurl_easy_init(3)\fP or
 Set the parameter to 1 to get the library to display a lot of verbose
 information about its operations. Very useful for libcurl and/or protocol
 debugging and understanding. The verbose information will be sent to stderr,
-or the stream set with \fICURLOPT_STDERR\fP.
+or the stream set with \fICURLOPT_STDERR\fP. The default value for this
+parameter is 0.
 
 You hardly ever want this set in production use, you will almost always want
 this when you debug/report problems. Another neat option for debugging is the
@@ -66,11 +67,11 @@ this when you debug/report problems. Another neat option for debugging is the
 .IP CURLOPT_HEADER
 A parameter set to 1 tells the library to include the header in the body
 output. This is only relevant for protocols that actually have headers
-preceding the data (like HTTP).
+preceding the data (like HTTP). The default value for this parameter is 0.
 .IP CURLOPT_NOPROGRESS
 Pass a long. If set to 1, it tells the library to shut off the progress meter
 completely. It will also prevent the \fICURLOPT_PROGRESSFUNCTION\fP from
-getting called.
+getting called. The default value for this parameter is 1.
 
 Future versions of libcurl are likely to not have any built-in progress meter
 at all.
@@ -79,6 +80,7 @@ Pass a long. If it is 1, libcurl will not use any functions that
 install signal handlers or any functions that cause signals to be sent to the
 process. This option is mainly here to allow multi-threaded unix applications
 to still set/use all timeout options etc, without risking getting signals.
+The default value for this parameter is 0.
 (Added in 7.10)
 
 If this option is set and libcurl has been built with the standard name
@@ -180,8 +182,9 @@ means 100K.
 .IP CURLOPT_WRITEDATA
 Data pointer to pass to the file write function. If you use the
 \fICURLOPT_WRITEFUNCTION\fP option, this is the pointer you'll get as
-input. If you don't use a callback, you must pass a 'FILE *' as libcurl will
+input. If you don't use a callback, you must pass a 'FILE *' (cast
-pass this to fwrite() when writing data.
+to 'void *') as libcurl will pass this to fwrite() when writing data.
+By default, the value of this parameter is unspecified.
 
 The internal \fICURLOPT_WRITEFUNCTION\fP will write the data to the FILE *
 given with this option, or to stdout if this option hasn't been set.
@@ -226,7 +229,7 @@ userdata set with \fICURLOPT_READDATA\fP.
 Data pointer to pass to the file read function. If you use the
 \fICURLOPT_READFUNCTION\fP option, this is the pointer you'll get as input. If
 you don't specify a read callback but instead rely on the default internal
-read function, this data must be a valid readable FILE *.
+read function, this data must be a valid readable FILE * (cast to 'void *').
 
 If you're using libcurl as a win32 DLL, you MUST use a
 \fICURLOPT_READFUNCTION\fP if you set this option.
@@ -240,13 +243,15 @@ gets called by libcurl when something special I/O-related needs to be done
 that the library can't do by itself. For now, rewinding the read data stream
 is the only action it can request. The rewinding of the read data stream may
 be necessary when doing a HTTP PUT or POST with a multi-pass authentication
-method.  (Option added in 7.12.3).
+method. By default, this parameter is set to NULL.  (Option added in 7.12.3).
 
-Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking!
+Use \fICURLOPT_SEEKFUNCTION\fP instead to provide seeking! If
+\fICURLOPT_SEEKFUNCTION\fP is set, this parameter will be ignored when seeking.
 .IP CURLOPT_IOCTLDATA
 Pass a pointer that will be untouched by libcurl and passed as the 3rd
-argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.  (Option
+argument in the ioctl callback set with \fICURLOPT_IOCTLFUNCTION\fP.
-added in 7.12.3)
+By default, the value of this parameter is unspecified.  (Option added in
+7.12.3)
 .IP CURLOPT_SEEKFUNCTION
 Pass a pointer to a function that matches the following prototype: \fBint
 function(void *instream, curl_off_t offset, int origin);\fP This function gets
@@ -255,13 +260,15 @@ used to fast forward a file in a resumed upload (instead of reading all
 uploaded bytes with the normal read function/callback). It is also called to
 rewind a stream when doing a HTTP PUT or POST with a multi-pass authentication
 method. The function shall work like "fseek" or "lseek" and accepted SEEK_SET,
-SEEK_CUR and SEEK_END as argument for origin, although (in 7.18.0) libcurl
+SEEK_CUR and SEEK_END as argument for origin, although libcurl currently only
-only passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on
+passes SEEK_SET. The callback must return 0 (CURL_SEEKFUNC_OK) on success, 1
-success, 1 (CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
+(CURL_SEEKFUNC_FAIL) to cause the upload operation to fail or 2
 (CURL_SEEKFUNC_CANTSEEK) to indicate that while the seek failed, libcurl is
 free to work around the problem if possible. The latter can sometimes be done
 by instead reading from the input or similar.
 
+By default, this parameter is unset.
+
 If you forward the input arguments directly to "fseek" or "lseek", note that
 the data type for \fIoffset\fP is not the same as defined for curl_off_t on
 many systems! (Option added in 7.18.0)
@@ -271,7 +278,8 @@ Data pointer to pass to the file seek function. If you use the
 you don't specify a seek callback, NULL is passed. (Option added in 7.18.0)
 .IP CURLOPT_SOCKOPTFUNCTION
 Pass a pointer to a function that matches the following prototype: \fBint
-function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. This
+function(void *clientp, curl_socket_t curlfd, curlsocktype purpose);\fP. By
+default, this parameter is unset. If set, this
 function gets called by libcurl after the socket() call but before the
 connect() call. The callback's \fIpurpose\fP argument identifies the exact
 purpose for this particular socket:
@@ -293,6 +301,7 @@ in fact already connected and then libcurl will not attempt to connect it.
 .IP CURLOPT_SOCKOPTDATA
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the sockopt callback set with \fICURLOPT_SOCKOPTFUNCTION\fP.
+The default value of this parameter is unspecified.
 (Option added in 7.16.0)
 .IP CURLOPT_OPENSOCKETFUNCTION
 Pass a pointer to a function that matches the following prototype:
@@ -317,6 +326,7 @@ blacklisting.  The default behavior is:
 .IP CURLOPT_OPENSOCKETDATA
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the opensocket callback set with \fICURLOPT_OPENSOCKETFUNCTION\fP.
+The default value of this parameter is unspecified.
 (Option added in 7.17.1.)
 .IP CURLOPT_CLOSESOCKETFUNCTION
 Pass a pointer to a function that matches the following prototype: \fBint
@@ -328,17 +338,40 @@ success and 1 if there was an error.  (Option added in 7.21.7)
 .IP CURLOPT_CLOSESOCKETDATA
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the closesocket callback set with
-\fICURLOPT_CLOSESOCKETFUNCTION\fP.  (Option added in 7.21.7)
+\fICURLOPT_CLOSESOCKETFUNCTION\fP.
+The default value of this parameter is unspecified.
+(Option added in 7.21.7)
 .IP CURLOPT_PROGRESSFUNCTION
-Pass a pointer to a function that matches the following prototype: \fBint
+Pass a pointer to a function that matches the following prototype:
-function(void *clientp, double dltotal, double dlnow, double ultotal, double
+
-ulnow); \fP. This function gets called by libcurl instead of its internal
+\fBint function(void *clientp, double dltotal, double dlnow, double ultotal,
-equivalent with a frequent interval during operation (roughly once per second
+double ulnow);\fP
-or sooner) no matter if data is being transferred or not.  Unknown/unused
+
-argument values passed to the callback will be set to zero (like if you only
+We encourage users to use \fICURLOPT_XFERINFOFUNCTION\fP instead, if you can.
-download data, the upload size will remain 0). Returning a non-zero value from
+
-this callback will cause libcurl to abort the transfer and return
+This function gets called by libcurl instead of its internal equivalent with a
-\fICURLE_ABORTED_BY_CALLBACK\fP.
+frequent interval. While data is being transferred it will be called very
+frequently, and during slow periods like when nothing is being transferred it
+can slow down to about one call per second.
+
+\fIclientp\fP is the pointer set with \fICURLOPT_PROGRESSDATA\fP, it is not
+actually used by libcurl but is only passed along from the application to the
+callback.
+
+The callback gets told how much data libcurl will transfer and has
+transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
+libcurl expects to download in this transfer. \fIdlnow\fP is the number of
+bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
+expects to upload in this transfer. \fIulnow\fP is the number of bytes
+uploaded so far.
+
+Unknown/unused argument values passed to the callback will be set to zero
+(like if you only download data, the upload size will remain 0). Many times
+the callback will be called one or more times first, before it knows the data
+sizes so a program must be made to handle that.
+
+Returning a non-zero value from this callback will cause libcurl to abort the
+transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
 
 If you transfer data with the multi interface, this function will not be
 called during periods of idleness unless you call the appropriate libcurl
@@ -346,9 +379,54 @@ function that performs transfers.
 
 \fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually
 get called.
+.IP CURLOPT_XFERINFOFUNCTION
+Pass a pointer to a function that matches the following prototype:
+
+.nf
+\fBint function(void *clientp, curl_off_t dltotal, curl_off_t dlnow,
+                curl_off_t ultotal, curl_off_t ulnow);\fP
+.fi
+
+This function gets called by libcurl instead of its internal equivalent with a
+frequent interval. While data is being transferred it will be called very
+frequently, and during slow periods like when nothing is being transferred it
+can slow down to about one call per second.
+
+\fIclientp\fP is the pointer set with \fICURLOPT_XFERINFODATA\fP, it is only
+passed along from the application to the callback.
+
+The callback gets told how much data libcurl will transfer and has
+transferred, in number of bytes. \fIdltotal\fP is the total number of bytes
+libcurl expects to download in this transfer. \fIdlnow\fP is the number of
+bytes downloaded so far. \fIultotal\fP is the total number of bytes libcurl
+expects to upload in this transfer. \fIulnow\fP is the number of bytes
+uploaded so far.
+
+Unknown/unused argument values passed to the callback will be set to zero
+(like if you only download data, the upload size will remain 0). Many times
+the callback will be called one or more times first, before it knows the data
+sizes so a program must be made to handle that.
+
+Returning a non-zero value from this callback will cause libcurl to abort the
+transfer and return \fICURLE_ABORTED_BY_CALLBACK\fP.
+
+If you transfer data with the multi interface, this function will not be
+called during periods of idleness unless you call the appropriate libcurl
+function that performs transfers.
+
+\fICURLOPT_NOPROGRESS\fP must be set to 0 to make this function actually
+get called.
+
+(Added in 7.32.0)
 .IP CURLOPT_PROGRESSDATA
 Pass a pointer that will be untouched by libcurl and passed as the first
 argument in the progress callback set with \fICURLOPT_PROGRESSFUNCTION\fP.
+The default value of this parameter is unspecified.
+.IP CURLOPT_XFERINFODATA
+Pass a pointer that will be untouched by libcurl and passed as the first
+argument in the progress callback set with \fICURLOPT_XFERINFOFUNCTION\fP.
+The default value of this parameter is unspecified. This option is an alias
+for CURLOPT_PROGRESSDATA. (Added in 7.32.0)
 .IP CURLOPT_HEADERFUNCTION
 Pass a pointer to a function that matches the following prototype:
 \fBsize_t function( void *ptr, size_t size, size_t nmemb, void
@@ -417,6 +495,10 @@ The data is header (or header-like) data sent to the peer.
 The data is protocol data received from the peer.
 .IP CURLINFO_DATA_OUT
 The data is protocol data sent to the peer.
+.IP CURLINFO_SSL_DATA_OUT
+The data is SSL/TLS (binary) data sent to the peer.
+.IP CURLINFO_SSL_DATA_IN
+The data is SSL/TLS (binary) data received from the peer.
 .RE
 .IP CURLOPT_DEBUGDATA
 Pass a pointer to whatever you want passed in to your
@@ -607,12 +689,20 @@ scheme://host:port/path
 
 For a greater explanation of the format please see RFC3986.
 
-If the given URL lacks the scheme, or protocol, part ("http://" or "ftp://"
+If the given URL lacks the scheme (such as "http://" or "ftp://" etc) then
-etc), libcurl will attempt to resolve which protocol to use based on the
+libcurl will attempt to resolve the protocol based on one of the following
-given host mame. If the protocol is not supported, libcurl will return
+given host names:
-(\fICURLE_UNSUPPORTED_PROTOCOL\fP) when you call \fIcurl_easy_perform(3)\fP
+
-or \fIcurl_multi_perform(3)\fP. Use \fIcurl_version_info(3)\fP for detailed
+HTTP, FTP, DICT, LDAP, IMAP, POP3 or SMTP
-information on which protocols are supported.
+
+(POP3 and SMTP added in 7.31.0)
+
+Should the protocol, either that specified by the scheme or deduced by libcurl
+from the host name, not be supported by libcurl then
+(\fICURLE_UNSUPPORTED_PROTOCOL\fP) will be returned from either the
+\fIcurl_easy_perform(3)\fP or \fIcurl_multi_perform(3)\fP functions when you
+call them. Use \fIcurl_version_info(3)\fP for detailed information of which
+protocols are supported by the build of libcurl you are using.
 
 The host part of the URL contains the address of the server that you want to
 connect to. This can be the fully qualified domain name of the server, the
@@ -627,17 +717,23 @@ http://192.168.0.1/
 
 http://[2001:1890:1112:1::20]/
 
-It is also possible to specify the user name and password as part of the
+It is also possible to specify the user name, password and any supported login
-host, for some protocols, when connecting to servers that require
+options as part of the host, for the following protocols, when connecting to
-authentication.
+servers that require authentication:
-
-For example the following types of authentication support this:
 
 http://user:password@www.example.com
 
 ftp://user:password@ftp.example.com
 
-pop3://user:password@mail.example.com
+imap://user:password;options@mail.example.com
+
+pop3://user:password;options@mail.example.com
+
+smtp://user:password;options@mail.example.com
+
+At present only IMAP, POP3 and SMTP support login options as part of the host.
+For more information about the login options in URL syntax please see RFC2384,
+RFC5092 and IETF draft draft-earhart-url-smtp-00.txt (Added in 7.31.0).
 
 The port is optional and when not specified libcurl will use the default port
 based on the determined or specified protocol: 80 for HTTP, 21 for FTP and 25
@@ -714,12 +810,50 @@ the HELO / EHLO command to the mail server at example.com.
 
 .B POP3
 
-The path part of a POP3 request specifies the mailbox (message) to retrieve.
+The path part of a POP3 request specifies the message ID to retrieve. If the
-If the mailbox is not specified then a list of waiting messages is returned
+ID is not specified then a list of waiting messages is returned instead.
-instead.
 
-pop3://user:password@mail.example.com - This lists the available messages
+pop3://user:password@mail.example.com - This lists the available messages for
-pop3://user:password@mail.example.com/1 - This retrieves the first message
+the user
+
+pop3://user:password@mail.example.com/1 - This retrieves the first message for
+the user
+
+.B IMAP
+
+The path part of an IMAP request not only specifies the mailbox to list (Added
+in 7.30.0) or select, but can also be used to check the UIDVALIDITY of the
+mailbox, to specify the UID, SECTION (Added in 7.30.0) and PARTIAL octets
+(Added in 7.37.0) of the message to fetch and to specify what nessages to
+search for (Added in 7.37.0).
+
+imap://user:password@mail.example.com - Performs a top level folder list
+
+imap://user:password@mail.example.com/INBOX - Performs a folder list on the
+user's inbox
+
+imap://user:password@mail.example.com/INBOX/;UID=1 - Selects the user's inbox
+and fetches message 1
+
+imap://user:password@mail.example.com/INBOX;UIDVALIDITY=50/;UID=2 - Selects
+the user's inbox, checks the UIDVALIDITY of the mailbox is 50 and fetches
+message 2 if it is
+
+imap://user:password@mail.example.com/INBOX/;UID=3/;SECTION=TEXT - Selects the
+user's inbox and fetches the text portial of message 3
+
+imap://user:password@mail.example.com/INBOX/;UID=4/;PARTIAL=0.1024 - Selects
+the user's inbox and fetches the first 1024 octets of message 4
+
+imap://user:password@mail.example.com/INBOX?NEW - Selects the user's inbox and
+checks for NEW messages
+
+imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows - Selects the
+user's inbox and searches for messages containing "shadows" in the subject
+line
+
+For more information about the individual components of an IMAP URL please
+see RFC5092.
 
 .B SCP
 
@@ -774,6 +908,19 @@ Active Directory server.
 For more information about the individual components of a LDAP URL please
 see RFC4516.
 
+.B RTMP
+
+There's no official URL spec for RTMP so libcurl uses the URL syntax supported
+by the underlying librtmp library. It has a syntax where it wants a
+traditional URL, followed by a space and a series of space-separated
+name=value pairs.
+
+While space is not typically a "legal" letter, libcurl accepts them. When a
+user wants to pass in a '#' (hash) character it will be treated as a fragment
+and get cut off by libcurl if provided literally. You will instead have to
+escape it by providing it as backslash and its ASCII value in hexadecimal:
+"\\23".
+
 .B NOTES
 
 Starting with version 7.20.0, the fragment part of the URI will not be sent as
@@ -806,9 +953,9 @@ Set HTTP proxy to use. The parameter should be a char * to a zero terminated
 string holding the host name or dotted IP address. To specify port number in
 this string, append :[port] to the end of the host name. The proxy string may
 be prefixed with [protocol]:// since any such prefix will be ignored. The
-proxy's port number may optionally be specified with the separate option. If
+proxy's port number may optionally be specified with the separate option
-not specified, libcurl will default to using port 1080 for proxies.
+\fICURLOPT_PROXYPORT\fP. If not specified, libcurl will default to using port
-\fICURLOPT_PROXYPORT\fP.
+1080 for proxies.
 
 When you tell the library to use a HTTP proxy, libcurl will transparently
 convert operations to HTTP even if you specify an FTP URL etc. This may have
@@ -855,8 +1002,8 @@ if one is specified.  The only wildcard available is a single * character,
 which matches all hosts, and effectively disables the proxy. Each name in this
 list is matched as either a domain which contains the hostname, or the
 hostname itself. For example, example.com would match example.com,
-example.com:80, and www.example.com, but not www.notanexample.com.  (Added in
+example.com:80, and www.example.com, but not www.notanexample.com or
-7.19.4)
+example.com.othertld.  (Added in 7.19.4)
 .IP CURLOPT_HTTPPROXYTUNNEL
 Set the parameter to 1 to make the library tunnel all operations through a
 given HTTP proxy. There is a big difference between using a proxy and to
@@ -1000,8 +1147,8 @@ the full path name to the file you want libcurl to use as .netrc file. If this
 option is omitted, and \fICURLOPT_NETRC\fP is set, libcurl will attempt to
 find a .netrc file in the current user's home directory. (Added in 7.10.9)
 .IP CURLOPT_USERPWD
-Pass a char * as parameter, which should be [user name]:[password] to use for
+Pass a char * as parameter, pointing to a zero terminated login details string
-the connection. Use \fICURLOPT_HTTPAUTH\fP to decide the authentication method.
+for the connection. The format of which is: [user name]:[password].
 
 When using NTLM, you can set the domain by prepending it to the user name and
 separating the domain and name with a forward (/) or backward slash (\\). Like
@@ -1014,10 +1161,21 @@ and password information to hosts using the initial host name (unless
 \fICURLOPT_UNRESTRICTED_AUTH\fP is set), so if libcurl follows locations to
 other hosts it will not send the user and password to those. This is enforced
 to prevent accidental information leakage.
+
+Use \fICURLOPT_HTTPAUTH\fP to specify the authentication method for HTTP based
+connections or \fICURLOPT_LOGIN_OPTIONS\fP to control IMAP, POP3 and SMTP
+options.
+
+The user and password strings are not URL decoded, so there's no way to send
+in a user name containing a colon using this option. Use \fICURLOPT_USERNAME\fP
+for that, or include it in the URL.
 .IP CURLOPT_PROXYUSERPWD
 Pass a char * as parameter, which should be [user name]:[password] to use for
-the connection to the HTTP proxy.  Use \fICURLOPT_PROXYAUTH\fP to decide
+the connection to the HTTP proxy. Both the name and the password will be URL
-the authentication method.
+decoded before use, so to include for example a colon in the user name you
+should encode it as %3A.
+
+Use \fICURLOPT_PROXYAUTH\fP to specify the authentication method.
 .IP CURLOPT_USERNAME
 Pass a char * as parameter, which should be pointing to the zero terminated
 user name to use for the transfer.
@@ -1026,14 +1184,26 @@ user name to use for the transfer.
 authentication. You should not use this option together with the (older)
 CURLOPT_USERPWD option.
 
-In order to specify the password to be used in conjunction with the user name
+To specify the password and login options, along with the user name, use the
-use the \fICURLOPT_PASSWORD\fP option.  (Added in 7.19.1)
+\fICURLOPT_PASSWORD\fP and \fICURLOPT_LOGIN_OPTIONS\fP options. (Added in
+7.19.1)
 .IP CURLOPT_PASSWORD
 Pass a char * as parameter, which should be pointing to the zero terminated
 password to use for the transfer.
 
-The CURLOPT_PASSWORD option should be used in conjunction with
+The CURLOPT_PASSWORD option should be used in conjunction with the
-the \fICURLOPT_USERNAME\fP option. (Added in 7.19.1)
+\fICURLOPT_USERNAME\fP option. (Added in 7.19.1)
+.IP CURLOPT_LOGIN_OPTIONS
+(Added in 7.34.0) Pass a char * as parameter, which should be pointing to the
+zero terminated options string to use for the transfer.
+
+At present only IMAP, POP3 and SMTP support login options. For more
+information about the login options please see RFC2384, RFC5092 and IETF draft
+draft-earhart-url-smtp-00.txt
+
+\fBCURLOPT_LOGIN_OPTIONS\fP can be used to set protocol specific login options,
+such as the preferred authentication mechanism via "AUTH=NTLM" or "AUTH=*",
+and should be used in conjunction with the \fICURLOPT_USERNAME\fP option.
 .IP CURLOPT_PROXYUSERNAME
 Pass a char * as parameter, which should be pointing to the zero terminated
 user name to use for the transfer while connecting to Proxy.
@@ -1094,7 +1264,7 @@ Microsoft. It uses a challenge-response and hash concept similar to Digest, to
 prevent the password from being eavesdropped.
 
 You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this
-option to work, or build libcurl on Windows.
+option to work, or build libcurl on Windows with SSPI support.
 .IP CURLAUTH_NTLM_WB
 NTLM delegating to winbind helper. Authentication is performed by a separate
 binary application that is executed when needed. The name of the application
@@ -1153,8 +1323,23 @@ authentication methods it supports and then pick the best one you allow it to
 use. For some methods, this will induce an extra network round-trip. Set the
 actual name and password with the \fICURLOPT_PROXYUSERPWD\fP option. The
 bitmask can be constructed by or'ing together the bits listed above for the
-\fICURLOPT_HTTPAUTH\fP option. As of this writing, only Basic, Digest and NTLM
+\fICURLOPT_HTTPAUTH\fP option. \fICURLOPT_PROXYAUTH\fP was added in 7.10.7
-work. (Added in 7.10.7)
+.IP CURLOPT_SASL_IR
+Pass a long. If the value is 1, curl will send the initial response to the
+server in the first authentication packet in order to reduce the number of
+ping pong requests. Only applicable to supporting SASL authentication
+mechanisms and to the IMAP, POP3 and SMTP protocols. (Added in 7.31.0)
+
+Note: Whilst IMAP supports this option there is no need to explicitly set it,
+as libcurl can determine the feature itself when the server supports the
+SASL-IR CAPABILITY.
+.IP CURLOPT_XOAUTH2_BEARER
+Pass a char * as parameter, which should point to the zero terminated OAuth
+2.0 Bearer Access Token for use with IMAP, POP3 and SMTP servers that support
+the OAuth 2.0 Authorization Framework. (Added in 7.33.0)
+
+Note: The user name used to generate the Bearer Token should be supplied via
+the \fICURLOPT_USERNAME\fP option.
 .SH HTTP OPTIONS
 .IP CURLOPT_AUTOREFERER
 Pass a parameter set to 1 to enable this. When enabled, libcurl will
@@ -1343,19 +1528,24 @@ set the User-Agent: header in the http request sent to the remote server. This
 can be used to fool servers or scripts. You can also set any custom header
 with \fICURLOPT_HTTPHEADER\fP.
 .IP CURLOPT_HTTPHEADER
-Pass a pointer to a linked list of HTTP headers to pass to the server in your
+Pass a pointer to a linked list of HTTP headers to pass to the server and/or
-HTTP request. The linked list should be a fully valid list of \fBstruct
+proxy in your HTTP request. The same list is used for both host and proxy
-curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
+requests!
-create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire
+
-list. If you add a header that is otherwise generated and used by libcurl
+The linked list should be a fully valid list of \fBstruct curl_slist\fP
-internally, your added one will be used instead. If you add a header with no
+structs properly filled in. Use \fIcurl_slist_append(3)\fP to create the list
-content as in 'Accept:' (no data on the right side of the colon), the
+and \fIcurl_slist_free_all(3)\fP to clean up an entire list. If you add a
-internally used header will get disabled. Thus, using this option you can add
+header that is otherwise generated and used by libcurl internally, your added
-new headers, replace internal headers and remove internal headers. To add a
+one will be used instead. If you add a header with no content as in 'Accept:'
-header with no content, make the content be two quotes: \&"". The headers
+(no data on the right side of the colon), the internally used header will get
-included in the linked list must not be CRLF-terminated, because curl adds
+disabled. With this option you can add new headers, replace internal headers
-CRLF after each header item. Failure to comply with this will result in
+and remove internal headers. To add a header with no content (nothing to the
-strange bugs because the server will most likely ignore part of the headers
+right side of the colon), use the form 'MyHeader;' (note the ending
+semicolon).
+
+The headers included in the linked list must not be CRLF-terminated, because
+curl adds CRLF after each header item. Failure to comply with this will result
+in strange bugs because the server will most likely ignore part of the headers
 you specified.
 
 The first line in a request (containing the method, usually a GET or POST) is
@@ -1367,6 +1557,42 @@ Pass a NULL to this to reset back to no custom headers.
 
 The most commonly replaced headers have "shortcuts" in the options
 \fICURLOPT_COOKIE\fP, \fICURLOPT_USERAGENT\fP and \fICURLOPT_REFERER\fP.
+
+There's an alternative option that sets or replaces headers only for requests
+that are sent with CONNECT to a proxy: \fICURLOPT_PROXYHEADER\fP. Use
+\fICURLOPT_HEADEROPT\fP to control the behavior.
+.IP CURLOPT_HEADEROPT
+Pass a long that is a bitmask of options of how to deal with headers. The two
+mutually exclusive options are:
+
+CURLHEADER_UNIFIED - keep working as before. This means CURLOPT_HTTPHEADER
+headers will be used in requests both to servers and proxies. With this option
+enabled, \fICURLOPT_PROXYHEADER\fP will not have any effect.
+
+CURLHEADER_SEPARATE - makes \fICURLOPT_HTTPHEADER\fP headers only get sent to
+a server and not to a proxy. Proxy headers must be set with
+\fICURLOPT_PROXYHEADER\fP to get used. Note that if a non-CONNECT request is
+sent to a proxy, libcurl will send both server headers and proxy headers. When
+doing CONNECT, libcurl will send \fICURLOPT_PROXYHEADER\fP headers only do the
+proxy and then \fICURLOPT_HTTPHEADER\fP headers only to the server.
+
+(Added in 7.37.0)
+.IP CURLOPT_PROXYHEADER
+Pass a pointer to a linked list of HTTP headers to pass in your HTTP request
+sent to a proxy. The rules for this list is identical to the
+\fICURLOPT_HTTPHEADER\fP option's.
+
+The headers set with this option is only ever used in requests sent to a proxy
+- when there's also a request sent to a host.
+
+The first line in a request (containing the method, usually a GET or POST) is
+NOT a header and cannot be replaced using this option. Only the lines
+following the request-line are headers. Adding this method line in this list
+of headers will only cause your request to send an invalid header.
+
+Pass a NULL to this to reset back to no custom headers.
+
+This option was added in libcurl 7.37.0.
 .IP CURLOPT_HTTP200ALIASES
 Pass a pointer to a linked list of aliases to be treated as valid HTTP 200
 responses.  Some servers respond with a custom header response line.  For
@@ -1445,11 +1671,12 @@ to GET. Usable if a POST, HEAD, PUT, or a custom request has been used
 previously using the same curl handle.
 
 When setting \fICURLOPT_HTTPGET\fP to 1, it will automatically set
-\fICURLOPT_NOBODY\fP to 0 (since 7.14.1).
+\fICURLOPT_NOBODY\fP to 0 and \fICURLOPT_UPLOAD\fP to 0.
 .IP CURLOPT_HTTP_VERSION
 Pass a long, set to one of the values described below. They force libcurl to
 use the specific HTTP versions. This is not sensible to do unless you have a
-good reason.
+good reason. You have to set this option if you want to use libcurl's HTTP 2.0
+support.
 .RS
 .IP CURL_HTTP_VERSION_NONE
 We don't care about what version the library uses. libcurl will use whatever
@@ -1458,6 +1685,9 @@ it thinks fit.
 Enforce HTTP 1.0 requests.
 .IP CURL_HTTP_VERSION_1_1
 Enforce HTTP 1.1 requests.
+.IP CURL_HTTP_VERSION_2_0
+Attempt HTTP 2.0 requests. libcurl will fall back to HTTP 1.x if HTTP 2.0
+can't be negotiated with the server.
 .RE
 .IP CURLOPT_IGNORE_CONTENT_LENGTH
 Ignore the Content-Length header. This is useful for Apache 1.x (and similar
@@ -1468,13 +1698,19 @@ connection. (added in 7.14.1)
 .IP CURLOPT_HTTP_CONTENT_DECODING
 Pass a long to tell libcurl how to act on content decoding. If set to zero,
 content decoding will be disabled. If set to 1 it is enabled. Libcurl has no
-default content decoding but requires you to use \fICURLOPT_ENCODING\fP for
+default content decoding but requires you to use \fICURLOPT_ACCEPT_ENCODING\fP
-that. (added in 7.16.2)
+for that. (added in 7.16.2)
 .IP CURLOPT_HTTP_TRANSFER_DECODING
 Pass a long to tell libcurl how to act on transfer decoding. If set to zero,
 transfer decoding will be disabled, if set to 1 it is enabled
 (default). libcurl does chunked transfer decoding by default unless this
 option is set to zero. (added in 7.16.2)
+.IP CURLOPT_EXPECT_100_TIMEOUT_MS
+Pass a long to tell libcurl the number of milliseconds to wait for a server
+response with the HTTP status 100 (Continue), 417 (Expectation Failed) or
+similar after sending a HTTP request containing an Expect: 100-continue
+header. If this times out before a response is received, the request body is
+sent anyway. By default, libcurl waits 1000 milliseconds. (Added in 7.36.0)
 .SH SMTP OPTIONS
 .IP CURLOPT_MAIL_FROM
 Pass a pointer to a zero terminated string as parameter. This should be used
@@ -1495,12 +1731,18 @@ SMTP mail request. The linked list should be a fully valid list of \fBstruct
 curl_slist\fP structs properly filled in. Use \fIcurl_slist_append(3)\fP to
 create the list and \fIcurl_slist_free_all(3)\fP to clean up an entire list.
 
-Each recipient should be specified within a pair of angled brackets (<>),
+When performing a mail transfer, each recipient should be specified within a
-however, should you not use an angled bracket as the first character libcurl
+pair of angled brackets (<>), however, should you not use an angled bracket as
-will assume you provided a single email address and enclose that address
+the first character libcurl will assume you provided a single email address and
-within brackets for you.
+enclose that address within brackets for you. (Added in 7.20.0)
 
-(Added in 7.20.0)
+When performing an address verification (VRFY command), each recipient should
+be specified as the user name or user name and domain (as per Section 3.5 of
+RFC5321). (Added in 7.34.0)
+
+When performing a mailing list expand (EXPN command), each recipient should be
+specified using the mailing list name, such as "Friends" or "London-Office".
+(Added in 7.34.0)
 .IP CURLOPT_MAIL_AUTH
 Pass a pointer to a zero terminated string as parameter. This will be used
 to specify the authentication address (identity) of a submitted message that
@@ -1872,35 +2114,32 @@ source file to the remote target file.
 Pass a curl_off_t as parameter. It contains the offset in number of bytes that
 you want the transfer to start from. (Added in 7.11.0)
 .IP CURLOPT_CUSTOMREQUEST
-Pass a pointer to a zero terminated string as parameter. It can be used to
+Pass a pointer to a zero terminated string as parameter.
-specify the request instead of GET or HEAD when performing HTTP based
-requests, instead of LIST and NLST when performing FTP directory listings and
-instead of LIST and RETR when issuing POP3 based commands. This is
-particularly useful, for example, for performing a HTTP DELETE request or a
-POP3 DELE command.
-
-Please don't perform this at will, on HTTP based requests, by making sure
-your server supports the command you are sending first.
 
 When you change the request method by setting \fBCURLOPT_CUSTOMREQUEST\fP to
 something, you don't actually change how libcurl behaves or acts in regards
 to the particular request method, it will only change the actual string sent
 in the request.
 
+Restore to the internal default by setting this to NULL.
+
+This option can be used to specify the request:
+
+.B HTTP
+
+Instead of GET or HEAD when performing HTTP based requests. This is
+particularly useful, for example, for performing a HTTP DELETE request.
+
 For example:
 
-With the HTTP protocol when you tell libcurl to do a HEAD request, but then
+When you tell libcurl to do a HEAD request, but then specify a GET though a
-specify a GET though a custom request libcurl will still act as if it sent a
+custom request libcurl will still act as if it sent a HEAD. To switch to a
-HEAD. To switch to a proper HEAD use \fICURLOPT_NOBODY\fP, to switch to a
+proper HEAD use \fICURLOPT_NOBODY\fP, to switch to a proper POST use
-proper POST use \fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and to switch
+\fICURLOPT_POST\fP or \fICURLOPT_POSTFIELDS\fP and to switch to a proper GET
-to a proper GET use CURLOPT_HTTPGET.
+use CURLOPT_HTTPGET.
 
-With the POP3 protocol when you tell libcurl to use a custom request it will
+Please don't perform this at will, on HTTP based requests, by making sure
-behave like a LIST or RETR command was sent where it expects data to be
+your server supports the command you are sending first.
-returned by the server. As such \fICURLOPT_NOBODY\fP should be used when
-specifying commands such as DELE and NOOP for example.
-
-Restore to the internal default by setting this to NULL.
 
 Many people have wrongly used this option to replace the entire request with
 their own, including multiple headers and POST contents. While that might
@@ -1910,7 +2149,35 @@ could possibly confuse the remote server badly. Use \fICURLOPT_POST\fP and
 replace or extend the set of headers sent by libcurl. Use
 \fICURLOPT_HTTP_VERSION\fP to change HTTP version.
 
-(Support for POP3 added in 7.26.0)
+.B FTP
+
+Instead of LIST and NLST when performing FTP directory listings.
+
+.B IMAP
+
+Instead of LIST when issuing IMAP based requests. (Added in 7.30.0)
+
+.B POP3
+
+Instead of LIST and RETR when issuing POP3 based requests. (Added in 7.26.0)
+
+For example:
+
+When you tell libcurl to use a custom request it will behave like a LIST or
+RETR command was sent where it expects data to be returned by the server. As
+such \fICURLOPT_NOBODY\fP should be used when specifying commands such as
+DELE and NOOP for example.
+
+.B SMTP
+
+Instead of a HELP or VRFY when issuing SMTP based requests. (Added in 7.34.0)
+
+For example:
+
+Normally a multiline response is returned which can be used, in conjuection with
+\fICURLOPT_MAIL_RCPT\fP, to specify an EXPN request. If the \fICURLOPT_NOBODY\fP
+option is specified then the request can be used to issue NOOP and RSET
+commands.
 .IP CURLOPT_FILETIME
 Pass a long. If it is 1, libcurl will attempt to get the modification date of
 the remote document in this operation. This requires that the remote server
@@ -1932,6 +2199,8 @@ as a long. See also \fICURLOPT_INFILESIZE_LARGE\fP.
 For uploading using SCP, this option or \fICURLOPT_INFILESIZE_LARGE\fP is
 mandatory.
 
+To "unset" this value again, set it to -1.
+
 When sending emails using SMTP, this command can be used to specify the
 optional SIZE parameter for the MAIL FROM command. (Added in 7.23.0)
 
@@ -1944,6 +2213,11 @@ as a curl_off_t. (Added in 7.11.0)
 
 For uploading using SCP, this option or \fICURLOPT_INFILESIZE\fP is mandatory.
 
+To "unset" this value again, set it to -1.
+
+When sending emails using SMTP, this command can be used to specify the
+optional SIZE parameter for the MAIL FROM command. (Added in 7.23.0)
+
 This option does not limit how much data libcurl will actually send, as that
 is controlled entirely by what the read callback returns.
 .IP CURLOPT_UPLOAD
@@ -2006,10 +2280,14 @@ In unix-like systems, this might cause signals to be used unless
 
 Default timeout is 0 (zero) which means it never times out.
 .IP CURLOPT_TIMEOUT_MS
-Like \fICURLOPT_TIMEOUT\fP but takes number of milliseconds instead. If
+An alternative to \fICURLOPT_TIMEOUT\fP but takes number of milliseconds
-libcurl is built to use the standard system name resolver, that portion
+instead. If libcurl is built to use the standard system name resolver, that
-of the transfer will still use full-second resolution for timeouts with
+portion of the transfer will still use full-second resolution for timeouts
-a minimum timeout allowed of one second.
+with a minimum timeout allowed of one second.
+
+If both \fICURLOPT_TIMEOUT\fP and \fICURLOPT_TIMEOUT_MS\fP are set, the value
+set last will be used.
+
 (Added in 7.16.2)
 .IP CURLOPT_LOW_SPEED_LIMIT
 Pass a long as parameter. It contains the transfer speed in bytes per second
@@ -2023,12 +2301,18 @@ it too slow and abort.
 Pass a curl_off_t as parameter.  If an upload exceeds this speed (counted in
 bytes per second) on cumulative average during the transfer, the transfer will
 pause to keep the average rate less than or equal to the parameter value.
-Defaults to unlimited speed. (Added in 7.15.5)
+Defaults to unlimited speed.
+
+This option doesn't affect transfer speeds done with FILE:// URLs. (Added in
+ 7.15.5)
 .IP CURLOPT_MAX_RECV_SPEED_LARGE
 Pass a curl_off_t as parameter.  If a download exceeds this speed (counted in
 bytes per second) on cumulative average during the transfer, the transfer will
 pause to keep the average rate less than or equal to the parameter
-value. Defaults to unlimited speed. (Added in 7.15.5)
+value. Defaults to unlimited speed.
+
+This option doesn't affect transfer speeds done with FILE:// URLs. (Added in
+7.15.5)
 .IP CURLOPT_MAXCONNECTS
 Pass a long. The set number will be the persistent connection cache size. The
 set amount will be the maximum amount of simultaneously open connections that
@@ -2133,7 +2417,9 @@ ADDRESS can of course be either IPv4 or IPv6 style addressing.
 
 This option effectively pre-populates the DNS cache with entries for the
 host+port pair so redirects and everything that operations against the
-HOST+PORT will instead use your provided ADDRESS.
+HOST+PORT will instead use your provided ADDRESS. Addresses to set with
+\fICURL_RESOLVE\fP will not time-out from the DNS cache like ordindary
+entries.
 
 You can remove names from the DNS cache again, to stop providing these fake
 resolves, by including a string in the linked list that uses the format
@@ -2155,6 +2441,36 @@ This option requires that libcurl was built with a resolver backend that
 supports this operation. The c-ares backend is the only such one.
 
 (Added in 7.24.0)
+.IP CURLOPT_DNS_INTERFACE
+Pass a char * as parameter. Set the name of the network interface that
+the DNS resolver should bind to. This must be an interface name (not an
+address). Set this option to NULL to use the default setting (don't
+bind to a specific interface).
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.
+
+(Added in 7.33.0)
+.IP CURLOPT_DNS_LOCAL_IP4
+Set the local IPv4 address that the resolver should bind to. The argument
+should be of type char * and contain a single IPv4 address as a string.
+Set this option to NULL to use the default setting (don't
+bind to a specific IP address).
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.
+
+(Added in 7.33.0)
+.IP CURLOPT_DNS_LOCAL_IP6
+Set the local IPv6 address that the resolver should bind to. The argument
+should be of type char * and contain a single IPv6 address as a string.
+Set this option to NULL to use the default setting (don't
+bind to a specific IP address).
+
+This option requires that libcurl was built with a resolver backend that
+supports this operation. The c-ares backend is the only such one.
+
+(Added in 7.33.0)
 .IP CURLOPT_ACCEPTTIMEOUT_MS
 Pass a long telling libcurl the maximum number of milliseconds to wait for a
 server to connect back to libcurl when an active FTP connection is used. If no
@@ -2162,20 +2478,28 @@ timeout is set, the internal default of 60000 will be used. (Added in 7.24.0)
 .SH SSL and SECURITY OPTIONS
 .IP CURLOPT_SSLCERT
 Pass a pointer to a zero terminated string as parameter. The string should be
-the file name of your certificate. The default format is "PEM" and can be
+the file name of your certificate. The default format is "P12" on Secure
-changed with \fICURLOPT_SSLCERTTYPE\fP.
+Transport and "PEM" on other engines, and can be changed with
+\fICURLOPT_SSLCERTTYPE\fP.
 
-With NSS this can also be the nickname of the certificate you wish to
+With NSS or Secure Transport, this can also be the nickname of the certificate
-authenticate with. If you want to use a file from the current directory, please
+you wish to authenticate with as it is named in the security database. If you
-precede it with "./" prefix, in order to avoid confusion with a nickname.
+want to use a file from the current directory, please precede it with "./"
+prefix, in order to avoid confusion with a nickname.
 .IP CURLOPT_SSLCERTTYPE
 Pass a pointer to a zero terminated string as parameter. The string should be
-the format of your certificate. Supported formats are "PEM" and "DER".  (Added
+the format of your certificate. Supported formats are "PEM" and "DER", except
-in 7.9.3)
+with Secure Transport. OpenSSL (versions 0.9.3 and later) and Secure Transport
+(on iOS 5 or later, or OS X 10.7 or later) also support "P12" for
+PKCS#12-encoded files. (Added in 7.9.3)
 .IP CURLOPT_SSLKEY
 Pass a pointer to a zero terminated string as parameter. The string should be
 the file name of your private key. The default format is "PEM" and can be
 changed with \fICURLOPT_SSLKEYTYPE\fP.
+
+(iOS and Mac OS X only) This option is ignored if curl was built against Secure
+Transport. Secure Transport expects the private key to be already present in
+the keychain or PKCS#12 file containing the certificate.
 .IP CURLOPT_SSLKEYTYPE
 Pass a pointer to a zero terminated string as parameter. The string should be
 the format of your private key. Supported formats are "PEM", "DER" and "ENG".
@@ -2193,6 +2517,20 @@ load your private key.
 
 (This option was known as CURLOPT_SSLKEYPASSWD up to 7.16.4 and
 CURLOPT_SSLCERTPASSWD up to 7.9.2)
+.IP CURLOPT_SSL_ENABLE_ALPN
+Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. By
+default, libcurl assumes a value of 1. This option enables/disables ALPN in
+the SSL handshake (if the SSL backend libcurl is built to use supports it),
+which can be used to negotiate http2.
+
+(Added in 7.36.0)
+.IP CURLOPT_SSL_ENABLE_NPN
+Pass a long as parameter, 0 or 1 where 1 is for enable and 0 for disable. By
+default, libcurl assumes a value of 1. This option enables/disables NPN in the
+SSL handshake (if the SSL backend libcurl is built to use supports it), which
+can be used to negotiate http2.
+
+(Added in 7.36.0)
 .IP CURLOPT_SSLENGINE
 Pass a pointer to a zero terminated string as parameter. It will be used as
 the identifier for the crypto engine you want to use for your private
@@ -2212,6 +2550,8 @@ Even though this option doesn't need any parameter, in some configurations
 arguments. Therefore, it's recommended to pass 1 as parameter to this option.
 .IP CURLOPT_SSLVERSION
 Pass a long as parameter to control what version of SSL/TLS to attempt to use.
+(Added in 7.9.2)
+
 The available options are:
 .RS
 .IP CURL_SSLVERSION_DEFAULT
@@ -2219,11 +2559,17 @@ The default action. This will attempt to figure out the remote SSL protocol
 version, i.e. either SSLv3 or TLSv1 (but not SSLv2, which became disabled
 by default with 7.18.1).
 .IP CURL_SSLVERSION_TLSv1
-Force TLSv1
+Force TLSv1.x
 .IP CURL_SSLVERSION_SSLv2
 Force SSLv2
 .IP CURL_SSLVERSION_SSLv3
 Force SSLv3
+.IP CURL_SSLVERSION_TLSv1_0
+Force TLSv1.0 (Added in 7.34.0)
+.IP CURL_SSLVERSION_TLSv1_1
+Force TLSv1.1 (Added in 7.34.0)
+.IP CURL_SSLVERSION_TLSv1_2
+Force TLSv1.2 (Added in 7.34.0)
 .RE
 .IP CURLOPT_SSL_VERIFYPEER
 Pass a long as parameter. By default, curl assumes a value of 1.
@@ -2324,9 +2670,10 @@ Curl considers the server the intended one when the Common Name field or a
 Subject Alternate Name field in the certificate matches the host name in the
 URL to which you told Curl to connect.
 
-When the value is 1, libcurl will return a failure. It was previously (in
+When the value is 1, \fIcurl_easy_setopt\fP will return an error and the option
-7.28.0 and earlier) a debug option of some sorts, but it is no longer
+value will not be changed.  It was previously (in 7.28.0 and earlier) a debug
-supported due to frequently leading to programmer mistakes.
+option of some sorts, but it is no longer supported due to frequently leading
+to programmer mistakes.
 
 When the value is 0, the connection succeeds regardless of the names in the
 certificate.
@@ -2336,14 +2683,14 @@ The default value for this option is 2.
 This option controls checking the server's certificate's claimed identity.
 The server could be lying.  To control lying, see
 \fICURLOPT_SSL_VERIFYPEER\fP.  If libcurl is built against NSS and
-\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_SSL_VERIFYHOST\fP
+\fICURLOPT_SSL_VERIFYPEER\fP is zero, \fICURLOPT_SSL_VERIFYHOST\fP is also set
-is ignored.
+to zero and cannot be overridden.
-
 .IP CURLOPT_CERTINFO
 Pass a long set to 1 to enable libcurl's certificate chain info gatherer. With
-this enabled, libcurl (if built with OpenSSL) will extract lots of information
+this enabled, libcurl (if built with OpenSSL, NSS, GSKit or QsoSSL) will
+extract lots of information
 and data about the certificates in the certificate chain used in the SSL
-connection. This data is then possible to extract after a transfer using
+connection. This data may then be retrieved after a transfer using
 \fIcurl_easy_getinfo(3)\fP and its option \fICURLINFO_CERTINFO\fP. (Added in
 7.19.1)
 .IP CURLOPT_RANDOM_FILE
@@ -2448,6 +2795,14 @@ known_host matching has been done, to allow the application to act and decide
 for libcurl how to proceed. The callback will only be called if
 \fICURLOPT_SSH_KNOWNHOSTS\fP is also set.
 
+.nf
+int curl_sshkeycallback (CURL *easy,     /* easy handle */
+                         const struct curl_khkey *knownkey, /* known */
+                         const struct curl_khkey *foundkey, /* found */
+                         enum curl_khmatch, /* libcurl's view on the keys */
+                         void *clientp);
+.fi
+
 The curl_sshkeycallback function gets passed the CURL handle, the key from the
 known_hosts file, the key from the remote site, info from libcurl on the
 matching status and a custom pointer (set with \fICURLOPT_SSH_KEYDATA\fP). It

docs/libcurl/curl_formadd.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2013, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -42,7 +42,7 @@ After the \fIlastitem\fP pointer follow the real arguments.
 The pointers \fIfirstitem\fP and \fIlastitem\fP should both be pointing to
 NULL in the first call to this function. All list-data will be allocated by
 the function itself. You must call \fIcurl_formfree(3)\fP on the
-\fIfirstitem\P after the form post has been done to free the resources.
+\fIfirstitem\fP after the form post has been done to free the resources.
 
 Using POST with HTTP 1.1 implies the use of a "Expect: 100-continue" header.
 You can disable this header with \fICURLOPT_HTTPHEADER\fP as usual.

docs/libcurl/curl_getdate.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, 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
@@ -21,22 +21,17 @@
 .\" **************************************************************************
 .TH curl_getdate 3 "12 Aug 2005" "libcurl 7.0" "libcurl Manual"
 .SH NAME
-curl_getdate - Convert a date string to number of seconds since January 1,
+curl_getdate - Convert a date string to number of seconds
-1970
 .SH SYNOPSIS
 .B #include <curl/curl.h>
 .sp
 .BI "time_t curl_getdate(char *" datestring ", time_t *"now " );"
 .ad
 .SH DESCRIPTION
-This function returns the number of seconds since January 1st 1970 in the UTC
+\fIcurl_getdate(3)\fP returns the number of seconds since the Epoch, January
-time zone, for the date and time that the \fIdatestring\fP parameter
+1st 1970 00:00:00 in the UTC time zone, for the date and time that the
-specifies. The \fInow\fP parameter is not used, pass a NULL there.
+\fIdatestring\fP parameter specifies. The \fInow\fP parameter is not used,
-
+pass a NULL there.
-\fBNOTE:\fP This function was rewritten for the 7.12.2 release and this
-documentation covers the functionality of the new one. The new one is not
-feature-complete with the old one, but most of the formats supported by the
-new one was supported by the old too.
 .SH PARSING DATES AND TIMES
 A "date" is a string containing several items separated by whitespace. The
 order of the items is immaterial.  A date string may contain many flavors of
@@ -108,10 +103,3 @@ number).
 Having a 64 bit time_t is not a guarantee that dates beyond 03:14:07 UTC,
 January 19, 2038 will work fine. On systems with a 64 bit time_t but with a
 crippled mktime(), \fIcurl_getdate\fP will return -1 in this case.
-.SH REWRITE
-The former version of this function was built with yacc and was not only very
-large, it was also never quite understood and it wasn't possible to build with
-non-GNU tools since only GNU Bison could make it thread-safe!
-
-The rewrite was done for 7.12.2. The new one is much smaller and uses simpler
-code.

docs/libcurl/curl_global_init.3

@@ -56,7 +56,8 @@ details of how to use this function.
 .SH FLAGS
 .TP 5
 .B CURL_GLOBAL_ALL
-Initialize everything possible. This sets all known bits.
+Initialize everything possible. This sets all known bits except
+\fBCURL_GLOBAL_ACK_EINTR\fP.
 .TP
 .B CURL_GLOBAL_SSL
 Initialize SSL
@@ -70,6 +71,10 @@ Initialise nothing extra. This sets no bit.
 .B CURL_GLOBAL_DEFAULT
 A sensible default. It will init both SSL and Win32. Right now, this equals
 the functionality of the \fBCURL_GLOBAL_ALL\fP mask.
+.TP
+.B CURL_GLOBAL_ACK_EINTR
+When this flag is set, curl will acknowledge EINTR condition when connecting
+or when waiting for data.  Otherwise, curl waits until full timeout elapses.
 .SH RETURN VALUE
 If this function returns non-zero, something went wrong and you cannot use the
 other curl functions.

docs/libcurl/curl_multi_add_handle.3

@@ -5,7 +5,7 @@
 .\" *                            | (__| |_| |  _ <| |___
 .\" *                             \___|\___/|_| \_\_____|
 .\" *
-.\" * Copyright (C) 1998 - 2011, Daniel Stenberg, <daniel@haxx.se>, et al.
+.\" * Copyright (C) 1998 - 2014, Daniel Stenberg, <daniel@haxx.se>, et al.
 .\" *
 .\" * This software is licensed as described in the file COPYING, which
 .\" * you should have received as part of this distribution. The terms
@@ -29,18 +29,26 @@ CURLMcode curl_multi_add_handle(CURLM *multi_handle, CURL *easy_handle);
 .ad
 .SH DESCRIPTION
 Adds a standard easy handle to the multi stack. This function call will make
-this \fImulti_handle\fP control the specified \fIeasy_handle\fP.
+this \fImulti_handle\fP control the specified \fIeasy_handle\fP.  Furthermore,
-Furthermore, libcurl now initiates the connection associated with the
+libcurl now initiates the connection associated with the specified
-specified \fIeasy_handle\fP.
+\fIeasy_handle\fP.
 
-When an easy handle has been added to a multi stack, you can not and you must
+While an easy handle is added to a multi stack, you can not and you must not
-not use \fIcurl_easy_perform(3)\fP on that handle!
+use \fIcurl_easy_perform(3)\fP on that handle. After having removed the handle
+from the multi stack again, it is perfectly fine to use it with the easy
+interface again.
 
 If the easy handle is not set to use a shared (CURLOPT_SHARE) or global DNS
 cache (CURLOPT_DNS_USE_GLOBAL_CACHE), it will be made to use the DNS cache
 that is shared between all easy handles within the multi handle when
 \fIcurl_multi_add_handle(3)\fP is called.
 
+If you have CURLMOPT_TIMERFUNCTION set in the multi handle (and you really
+should if you're working event-based with \fIcurl_multi_socket_action(3)\fP
+and friends), that callback will be called from within this function to ask
+for an updated timer so that your main event loop will get the activity on
+this handle to get started.
+
 The easy handle will remain added until you remove it again with
 \fIcurl_multi_remove_handle(3)\fP. You should remove the easy handle from the
 multi stack before you terminate first the easy handle and then the multi